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Chapter 1: 

CHAMELEON 32 

APPLICATION PROGRAMMING INTERFACE 


Introduction 


The Application Programming Interface (API) is designed to 
provide a uniform user -interface for applications created on 
the Chameleon 32. These applications and the user interface 
are created within the Chameleon 32 C Development System, 


The look and feel provided by this package is similar to pull 
down menu packages common in many other environments. 


The library provides tools to develop standardized and 
modular application code facilitating enhancements, readability 
and transferability of code. 


This document assumes some familiarity with the Chameleon 
32 C Package. For more detailed information than wh'at is 
provided here, refer to the Chameleon 32 C Manual , Volume 
IV. 

Applications developed using the API can be run on both a 
Chameleon 32 and a Chameleon 20 containing the C run-time 
module. 


API provides a quick and effective way to develop a user 
interface. Using this type of interface, you can: 


• transfer information to and from the application 

• provide easy access to the current configuration 
parameters 

• modify the parameters during runtime 

• verify that any changes made are within a valid range 

• make selections from a list of options 

• select a file from a specified path 

• chain lists and parameter input fields in any order 
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The functions within the API library provide you with complete 
control over all of the attributes regarding both the look and 
function of each part of the display. 

• The boxes and windows can be overlayed. 

• For each box or window, the following attributes are easily 
controlled: 

► location of the window or box on the screen 

► appearance of the window or box including: 

- borders 

- surrounding arrows 

- highlighting of current selection 

- position of the text within the box or window 

- color of the text, highlight and outline 

- parameter input as either hex, integer or string 

- automatic range checking 

- prompting the user when input is required 
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Installation 

Instructions 


The API software is installed through the Chameleon 32 C 
shell using the batch file INSTALL included on the diskette. 

To install the software, at the C prompt %, enter: 

BATCH B:\INSTALL 

This batch file creates the necessary directories and copies 
both the Library and Example fiies. The files are copied to the 
directories shown in Figure 1.1. 


FILENAME: 

- 

DESCRIPTION 

DIRECTORY 

libui.a 

API Library . 

AfLIB 

mainsym.h 

General symbols 

A: .INCLUDE 

ui.h 

API specific symbols 

A: INCLUDE 

SELECT. C 

Ex. 1, Pull Down Menus 

A: USR'-AP!\EX1 

MAKEFILE 

Creates example 1 

A: USR’APLEXl 

UITAB.C 

API table for example 1 

A: USR'APLEXl 

UITAB.H. 

API externals for example 1 

A: USR’APl EX1 

EX2.C 

Ex. 2, Parameter Input 

A: USRAPLEX2 

MAKEFILE 

Creates example 2 

A: .USR\API'EX2 

UITAB.C 

API table for example 2 

A: .USR\AP!\EX2 

UITAB.H 

API externals for example 2 

A: USR\API',EX2 

EX3.C 

Ex. 3, Listing Files 

A:.USR'API£X3 

MAKEFILE 

Creates example 3 

A: ,USR'AP1\EX3 

UITAB.C 

API table for example 3 

A:\USRAP1\EX3 

UITAB.H 

API externals for example 3 

A: USRAPI\EX3 


Figure 1.1: Installation and File Directories 


Note that the UITAB.C and UITAB.H fiies for each example are 
j not the same. They contain the unique definitions that create 
the display for each example. 
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User Interface 

Components A user interface created using the Application Programming 

interface consists of boxes and windows. A box, or list 
selector, contains several strings of information, with each 
string made up of one. field. These are typically used to 
display a group of options, for example commands or 
messages, and then to accept a selection from the user. 

There are two types of windows. The simplest type displays 
strings of information that can scroll either up or down within 
the window. The second type displays strings of information 
at a fikpd location. 

Within the second type of window, the information displayed 
can take two forms, either an unformated string or a field 
made up of two parts, a title or description and a value. A 
field can be used to accept ujser input, this is called an input 
field. A window can contain a 'sequence of input fields. 

Figure 1-.2 is an example of an interface created using the 
application programming interface. This menu is used in the 
NT/TE Simulator for the Chameleon 32 or 20. It consists of 
:| three windows and one box. 

• The first window displays the menu strip along the top edge 
of the page. On this window, the borders and the selection 
highlight are turned off. This is an unformatted string. 


• The second window displays the name of the application 
along the bottom edge. 



Figure 1.2: The User Interface 
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Ch. 1: Introduction 


• The status shown on the page is shown within the third 
window. Each field has a description with an associated 
value. For example, the description of the first variable is 
Simulator and the value is NT. This is an example of a 
window containing fields. 

• The box is the session list selector. It is used to select 
from a group of session commands. 

A standard set of keys are used to move around or exit from 
the boxes and windows. The arrow keys, f | are used to 
move within a frame, where a frame , is either a box or a 
window. The keys GO, ESC, CAN and RTN are used to exit a 
frame. The action taken is determined through the software. 


Application Programming 
Interface Library 

The Application Programming Interface Library provides nine 
functions and nine commands or requests. The functions, 
described in Chapter 3, use the data structures established 
through, the requests, to display the appropriate information. 
This section provides a brief description of each function and 
request. 


FUNCTIONS 

Two of the functions provide the majority of the API 
functionality. 

• initUI 

This function is used to initialize the user interface. It is 
used only once, when the interface is first started. It 
performs the following functions: 

► it specifies the window and box administration areas 

► it defines the number of windows and boxes that make 
up the display 

► it initiates an error window 


• userlnterface 

The user interface is . a request oriented library. To initiate 
any of the nine requests, the appropriate data structures 
are set up and a call is made to the function 

userlnterface. 

This is the primary function within the API, All' requests are 
initiated through this function. 


TEKELEC 


1-5 


7 27 90 



Application Programming Interface 


Ch. 1: Introduction 


The seven additional- functions, shown in Figure 1 .3, are used 
in conjunction with the request BOX_REQ. They are used to 
control the information displayed within a box. 


FUNCTION 

OPERATION DESCRIPTION 

addNewLine 

Adds a new line to a list selector. 

cSToggle 

Toggles between a tag, for example the character 
and a blank space at a designated location within a 
list selector. 

eraseEOS 

Erases the screen from line 3 downward. 

fillBoxArea 

Initializes a box for use! 

getBoxArea 

Allocates space to the scrolling area of a list selector. 

getFileChoice 

Initializes a list box to display file names from a 
specified path. 

unMark 

Removes all Marks set within a list selector. 


Figure 1.3: Additional API Functions 


Each of these functions are described in detail in Chapter 3. 
Examples showing their use are provided in Chapter 5. 
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REQUESTS 

The nine requests are summarized in Figure 1.4. The details 
can be found in Chapter 4. 


REQUEST 

PAGE 

OPERATION DESCRIPTION ■' 

BOX_INPUT 

4.3 

Create a list selector at run-time. This 
allows a dynamic creation of choices. 

BOX_REQ 

4.5 

Display a box or list selector. 

DSP_REQ 

4.11 

Display text within the window. 

ERASE_F!ELD 

4.13 

Erase an entire field, both the value 
and the description, from the screen. 

ERASEB_REQ 

4.15 

Erase a box or list selector. 

ERASEW_REQ 

4.16 

Erase a window from the screen. 

INPUT_REQ 

4.17 

Display a sequence of fields to be. 
edited. 

REi REQ 

4.22 

Releases the memory allocated for a 
specific window. 

W!NDOW_REQ 

4.23 

Initialize the window description. 


Figure 1.4: Application Programming Interface Requests 
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Chapter 2: 

APPLICATION PROGRAMMING INTERFACE 
DEVELOPMENT ENVIRONMENT . 


Introduction The Application Programming Interface (API) is accessed in 

the format of a library similar to the other libraries available 
within the Chameleon 32 C Development system; Refer to the 
Chameleon 32 C Manual, Volume IV for general information on 
include files, library files and the method of building an 
application. 


Application Programming 
Interface Files 


There are five files used during the development of an 
application program interface. The first three are provided 
with the Application Programming Interface package. They 
provide the following functions: 

• libul.a 

The file libui.a is the library file which contains all of the 
logic behind the library functions. It is located in the 
directory A:\LJB. 

This file is used at link time. For example -LUI in the 
command, cc -0 MENU uitab.c -LUI, links the ui.a library to 
your source code. 

• ui.h 

The file ui.h is the header fiie which includes all of the 
definitions and structures used as arguments for the library 
functions. It is located in the directory A:\inciude. 

Ui.h is shown in Appendix A of this document. It must be 
included in the source code as shown in the examples 
found in Chapter 5. 

#include < ui.h > 
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* mainsym.h 

The file mainsym.h is the header file which includes the 
definitions for internal type declarations and Chameleon 
specific attributes such as key codes or colors. It is 
located in the directory A:\inciude. 

Mainsym.h is shown in Appendix B of this document. It 
must be included in the . source code as shown in the 
examples provided in Chapter 5. 

#include < mainsym.h > 

NOTE: mainsym.h must be included before ui.h. 


The remaining two files are application unique. They are part 
of the application files. ; These files are not required but are 
recommended to provide a uniformity between all applications 
using this package. 

• uitab.c 

The file uitab.c is the user interface program file which 
contains the initialization of structure parameters for each 
menu request. It is located in the development directory. 

• uitab.h 

The file uitab.h is the header file which includes the 
external declaration of the declarations made in uitab.c. It 
is located in the development directory. 
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Building an 
Interface File 


Global 

Initializations 


The following example illustrates how these files are used to 
build the executable interface file. 

-\ 

cc -o MENU menu.c uitab.c -LUI 


Each part of this command is defined as follows: 

• cc The command used to compile and link. 

• -o This option for the cc command is used to name 

the resulting executable file other than the 
standard A.out. In this example, the file is output 
to MENU. 


• MENU This is the name associated with the -o 

command. After a successful link and compile, it 
will contain the executable file. 

• menu.c The main program of the sample application. 

• uitab.c Initialization code for the request parameters. 


• -LUI The user interface library (libui.a) to link with. 


When using the API library, the following structures and 
definitions must be declared: 

N U M_0 F_WI N DOWS 

NUM_OF_BOXES 

DISPLAY dsp [NUM_OF_WINDOWSj 

BOX box [NM_OF_BOXES] 

error_window 

err_str 

errDsp 

noTitle 

The example shown on the following page illustrates these 
initializations. Further examples can be found in Chapter 5. 
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r Mandatory definitions and external declarations, 
for example in the fiie uitab.h 7 


#define 

ERROR_WIN 

0 

f* These parameters 

7 

#define 

NUM_OF__WINDOWS 

30 

r define the number of 

7 

# define 

NUM_OF_BOXES 

30 

r windows and boxes 

7 




r active at any time 

7 




A within an application. 

7 

extern DISPLAY 

dsp[] ; 


extern BOX 

box[]; 



extern WiNDOWREQ error_win; 


extern FIELD errStr = {22, 1, NIL}; 

/* Mandatory declarations, for example in the file uitab.c 7 

DISPLAY dsp[NUM_OF_WINDOWS]; r System configuration. 7 
BOX box(NUM_OF_BOXES]; /* System configuration. 7 

FIELD errStr = {22, 1, NIL}; 

DSPREQ errDsp = 

{ 

DSP_REQ, 

0 , 

ERR_WIN, 

(byte *) & errStr 

}; 

FIELD noTitie = {1,1; “”'}; t* empty string 7 

WINDOWREQ err_win = 

{WINDOW-REQ, 0, ERROR-WIN, STATIC, 40,. 40, ‘2’, 1, 20, 
FALSE, 20, 20, NOF, FALSE, T, &noTitle, NIL}; 
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Chapter 3: 

APPLICATION PROGRAMMING INTERFACE 
LIBRARY FUNCTIONS 


Introduction 


A user interface created using AP! directs any input from the 
keyboard or output to the screen through a set of requests. 
Ail types of requests are initiated through the function 
userlnterface{) with the first parameter defining the request 
type. This function, aiong with initUI for interface initialization 
provide the main functionality of the user interface. These are 
summarized in Figure 3.1. 


REQUEST 

PAGE 

■ 

OPERATION DESCRIPTION 

. initUI 

3.12 

Initializes the user interface. 

userlnterface 

3.14 

■Provides. access to the user interface. 


Figure 3.1: API (Main) Functions 


The seven additional functions can be thought of as Help 
functions. They are used with the request types BOX_REQ 
and BOX_INPUT. These functions are summarized in Figure 
3.2, 


REQUEST 

PAGE 

OPERATION DESCRIPTION 

add New Line. 

3.3 

Adds a new line to a list selector. 

cSToggle 

3.4 

Toggles between a tag, for eachampie 
the character * and a blank space at a 
designated location . 

eraseEOS 

3.6 

Erases the screen from line 3 
downward. 

fillBoxArea 

3.7 

Initializes a box for use. 

getBoxArea 

3.8 

Allocates space to the scrolling area of 
a list selector. 

getFiieChoice 

3.9 

Initializes a list box to display file names 
from a specified path. 

unMark 

3.13 

Removes all Marks set within a list 
selector. (See cSToggle to remove just 
one Mark.) 


Figure 3.2: Additional API (Help) Functions 
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Ch. 3: Library Functions 


A complete description of both types of functions can be found 
in an alphabetical listing in the following pages. 

The structures corresponding to the different request types, 
shown in capital letters, are defined in the include file, ui.h , 
and in Chapter 4 of this document. 
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addNewLineQ 

Declaration 

Description 


Return Value 

Related 

Functions 

Example 


addNewLine (s, str) 
SCRAREA *s; 
byte 'str; 


The function addNewLine inserts one line at a time to a list 
selector. This function should be used in conjunction with 
getBoxArea(). 

AddNewLineQ should be used when fillBoxAreaQ is not 
convenient, for example, when the contents of a list selector is 
determined during runtime of the application or the entries are 
to be retrieved from a file; 

The last line inserted must be equal to the empty string. An 
error will occur if more lines are added than defined by the 
BOXREQ parameter lines. You can however, have less 
entries. 

The parameters used with this function are defined as follows: 

*s A pointer to the scrolling area of a BOXREQ. 

*str A pointer to the string to be inserted. All 
inserted strings must be the same length. 


None 


getBoxAreaO 

The following example uses addNewLine to define the 
contents of a list selector. 

BOXREQ myBox * { }; /* initialized parameters*/ 

getBoxArea (&myBox); 


addNewLine (myBox.p, "Title String"); 
addNewLine (myBox.p, "My Choice"); 
addNewLine (myBox.p, "Your Choice" ) ; 

addNewLine {myBox.p, ""); /’mandatory last string*/ 


userlnterf ace (&myBox, &conf, dsp, box); 
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cSToggle () 


Declaration cSToggie (s, n, mode, ch, chi) 

SCRAREA *s; 

int n, mode;- 

char ch, chi; 


Description The cSToggle function is used to mark a specified position 

within a box or list selector with a character, for example an 
asterisk. This feature can be used in two ways. 

• When multiple selections are made within the list selector, 
this can be used to mark each selection. 

• For a- single selection box, it can be used to clarify the 

selection. ■ 

The parameters used with this function are defined as follows: 

s A pointer to the scrolling area within a BOXREQ 

n The position within the box 

mode 0 Toggle 

1 Set 

ch First marker character 

chi Second marker character 

If mode is set to Toggle, the function checks for the current 
state of the marker. If it currently contains chi, it is set to ch. 
For anything else, it is set to chi. 

Note: In order to use this feature, each selectable entry in a 

box should begin with a blank. 

The structure BOXREQ is defined in Chapter 4 with the 
command BOX_REQ. 


Return Value The output is a value of 0 or 1 . 

• 0 Set to first marker, ch. 

• 1 Set to second marker, chi. 


Related 

Functions The function unMarkQ can be used to clear ail marks within a 

box. 
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Examples 


. 


i 


TEKELEC 


The first example illustrates the function when several test 
cases are chosen from the list for a particular scenario. Each 
test case selected is marked with an asterisk. Note that a test 
case can be deselected by chosing it again and calling the 
function csToggieQ which is set to toggle. 


Test Cases 


tstl . tst 

* 

tst2.tst 

* 

tst3.tst 


tst4 . tst 

* 

tstS . tst 

* 

tste.tst 


tst7 . tst 


tstS.tst 


for ( ;;) 

{ 

userlnterf ace (itest_bax .icon f .dps , box ) ; 
if ( conf . exe=-G0 or conf . ex t==ESC ) break; 
csToggle (text_box.p, conf .choice, |o, ' '); 

test_box . setRow = conf. row;/* see BOX_REQ for */ 
/•description of setRow •/ 
test_box . of f set = conf. choice; 

} 

test_box . setRow * test_box . row; 
test_box .off set = 0; 


In the second example, a list of .c files is presented in a list 
selector. • The file tst3.c has been selected. The function 
csToggleQ is used to mark the selection, then redisplay the 
box. At this point, no additional choices are given to the user, 


Files 
tsti.c 
tstZ.c 
* tst3.c 

tSt4 . C 
tSt5 . c 

tst6. c 


userlnterf ace( if i 1 e_box .icon f , dps, box) ; 
csToggle (file_box.p, conf. choice, 0, '*'); 

file_box. choice = FALSE; 
userlnterf ace (if i 1 e_box , icon f , dps .box ) ; 
f ile_box. choi ce = TRUE; 
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eraseEOS() 

Declaration 

Description 

Return Value 

Related 

Functions 


eraseEOS() 

This function erases the screen- from line 3 downward. It is 
useful in conjunction with pull down menu logic. 

There are no parameters required with this function. 

. i 

None 


None 


i 
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fillBoxArea () 


Declaration 


Description 


fillBoxArea (req, striist) 
BOXREQ ’req; 
byte ’striist}]; 


This function initializes the scrolling linked list located within 
the structure BOXREQ. This must be done once, typically in 
the beginning of the program, before a box or list selector can 
be accessed through a call to userlnterface(). 

The parameters are defined as follows: 

req A pointer to BOXREQ 

. striist address of the array containing the strings to be 
entered in the list box , 

The structure BOXREQ is defined in Chapter 4 with the 
command BOX_R£Q. 


Return Value None 

Related 

Functions None 


Example This example illustrates the use of the function fillBoxArea}). 


BOXREQ message_list = { } ; 

byte *messtist[] = {" SETUP". 

' • ALERT", 
’ CALL PR", 


/* in.itial i-zed with parameters */ 
/* observe that each */ 
/* string must have */ 
/* the same length */ 


}: 

fillBoxArea {&message_l i s t , messList); 


See the beginning of example 1 in Chapter 5 for an efficient 
way of initializing several boxes in a row. 
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getBoxAreaQ 

Declaration 

Description 

Return Value 

Related 

Functions 


getBoxArea (breq) 
BOXREQ ’breq; 


This function allocates space to the scrolling area of a list 
selector. The linked list is also initialized. If the area needs to 
be re-initialized at any point, this function can be called again. 

No strings are put into the list selector. This is done with the 
function addNewLineQ. 

The pointer ’breq, points to the structure BOXREQ. This 
strucutre is define in Chapter 4 with the command BOX_REQ. 


None 


addNewLineQ 

fiilBoxAreaQ 
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getFileChoice () 

Declaration 


Description 


r~Ch: 3: Library Functions 


getFiieChoice (boxName, fPath, ext, bTitle, errMsg, 

insFIag, inserts, fnum,. conf) 


BOXREQ 

’boxName; 

byte 

IPath; 

byte 

’ext; 

byte 

’bTitle: 

byte- 

’errMsg; 

int 

insFIag 

byte 

” inserts; 

int 

fnum; 

BOXCONF. 

’conf; 


This function is used to display, a list of files. The function 
reads the directory specified by the path for each occurance 
of a file with the specified extension. For each occurance, the 
filename is loaded into the list selector. 

A call to the function fillBoxArea() is not necessary to initialize 
the scroll area within the box as that is done within the function 

getFileChoiceQ. 


The parameters used with this function are defined as follows: 


’boxName 

Ipath 

*ext 

’bTitle " 
’errMsg ' 


insFIag f 


”inserts f 


A pointer to BOXREQ 
The directory path 

The file extension, three character 
maximum withoutThe period 

The title string to be displayed within the 
list selector 

The error string that will be displayed at the 
bottom of the screen if no files exist. It is 
recommended to end this string with Press 
CAN to continue since this is required to 
continue. 

When set to TRUE, this inserts the number 
of lines 1 specified in fnum into the list box. 
Otherwise, set to FALSE. 

A pointer to an array of strings to be 
inserted when insFIag = TRUE. Otherwise 
set to NIL. 
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Return Value 


Related 

Functions 


fnum f When insFlag is set to true, this is the 
number of lines to be inserted. 

*conf A pointer to the BOXCONF structure. 

The structures BOXREQ and BOXCONF are defined in Chapter 
4 with the command BOX_REQ. 


This function contains an optional insert feature that permits 
you to insert strings into the list selector prior to the filenames. 
The insert strings are defined by an array of pointers. This 
utilizes the parameters insFlag, inserts and fnum. 

The second example illustrates this feature. 

Note: Each time the function getFileChoice is called, the 

BOXREQ scroll area is reinitialized and all entries are 
reloaded into the list selector. 

Refer to Example 3 in Chapter 5 at the function 
handle_Ioad(), for an illustration on using this 
function in conjunction with csToggie. 


The BOXCONF structure contains exit information. 

This parameter conf.str contains the filename which can be 
used to open the specified file. 


None 
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Example 


The first example uses, the function getFileChoiceQ to display 
a box containing the file names in the directory 
A:\TEKELEC\SYSTEM with the extension .co. It does not 
include the optional inserts. 


BOXREQ my_box = { }; /* initialized parameters */ 

getFileChoi ce (&my_box, "WTekel ecWsystemW" , "co", "CO FILES", 

"Sorry no .co files. Press CAN to continue", FALSE, 

NIL, 0, Sconf } ; 

/* conf.str contains file name */ 


The second example illustrates that same list selector with the 
additional inserts. Note that the strings within the insert must 
be the same length as the title string. The length of the title 
string must be calculated to fit within the length specified by 
the parameter len in the BOXREQ structure. 


BOXREQ my_box = { }; /* initialized parameters •/ 

byte *mylnserts[] = {" NEW ", 

" DELETE ", 

" DEFAULT "}; 

getFileChoice (&my_box, ’'^\Tekelec^^syste^l\\ , ' , ’’co”, "CO FILES", 

"Sorry no .CO files. Press CAN to continue", TRUE, 
mylnserts, 3, Sconf); 

/* conf.str contains file name */ 
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initUI () 


Declaration initUI (dsp, box, req, nw, nb) 

DISPLAY ’dsp; 

BOX ’box; 

W1NDOWREQ ’req; 
int nw; 

int nb; 


Description This function initializes the user interface. initUIQ must be 

called before any other call is made to the interface. 

The parameters used with this function are defined as follows: 

'dsp . A pointer to the window administration area 

’box A pointer to the list box administration area 

*req window initiation of ERROR_WINDOW 
(This is required) 

nw NUM_OF_WINDOWS 

nb NUM_OF_BOXES 

The structure types DISPLAY' and BOX are internal to the 
userlnterface function. !n order to use the API, both of these 
administration areas must be initialized within the user 
application. This is typically done within uitab.c. 

. Refer to Chapter 2 for the declaration of dsp, box, 
NUM_OF_WINDOWS, NUM_OF_BOXES and ERROR_WINDOW 

The structure type WINDOWREQ is defined in Chapter 4 with 
the command WINDOW_REQ. 


Return Value None. 
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unMark () 

Deciaration 

Description 

Return Value 

Related 

Functions 

Example 


unMark (s) 
SCRAREA *s; 


This function removes all marks used to identify selections 
within a list box. The parameter used with this function is 
defined as follows: 

*s A scroll area within the box to be cleared 


None 


See cSToggle() for information on marking selections. 


The following example clears all selections within the box 
specified by myBox. 

BOXREQ mybox = { /* initialized parameters */ 

unMark (myBo^.p); 
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userinterface () 


Deciaration 


Description 


Return Value 


userinterface (req, conf, dsp, box) 
byte . *req; 

byte *conf; 

DISPLAY *dsp; 

BOX *box: 


This function gives the user access to the user interface. 
Each of the requests or commands described in Chapter 4 is 
initiated through a call to this function. 

The parameters used with this function are defined as follows: 

req A pointer to the structure containing the request 
type or event 

conf A pointer to the return value 

dsp A pointer to the window administration area 

box . .A pointer to the list box administration area 


Note: The administration areas dsp and box must have 

been previously initialized by calling the function 
initUI(). This is typically done at the beginning of the 
program. 


The output is put in a structure of the type CONFIRM, where 
applicable. This is defined uniquely for each of the requests in 
Chapter 4. 
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Introduction 


Chapter 4: 

APPLICATION PROGRAMMING INTERFACE , 
LIBRARY REQUESTS 


The Application Programming Interface library provides nine 
requests or commands. A brief description of each of these is 
shown in Figure 4.1. 


REQUEST 

PAGE 

OPERATION DESCRIPTION 

l 

BOX_INPUT 

4.3 

Create a user edited list selector. This 
allows runtime configured lists of 
choices. 

i 

BOX_REQ 

4.4 

1 

Display a box or list selector. 

DSP_REQ 

4.7 

Display text within the window. 

ERASE_F!ELD 

4.9 

Erase an entire field, both the value 
and the description, within a window. 

"ERASEB_REQ 

4.11 

Erase a box or list selector. 

ERASEW_REQ • 

4.12 

Erase a window from the screen. 

INPUT_REQ 

4.13 

Display a sequence of fields to be 
edited. 

REL_REQ 

| 

•4.17 

Releases the memory allocated for a 
specific window. 

W!NDOW__REQ 

4.13 

Initialize the window description. 


Figure 4.1: Application Programming Interface Requests 


Each of these requests is made up of structures defining the 
parameters required to complete the request. Once the 
parameters within each structure are defined, a call is made to 
the function userlnterface. It utilizes the information in the 
structures to complete the request. 

The userlnterface function, along with initUI and the 
additional API (Help) functions are described in Chapter 3 of 
this document. 


TEKELEC 


4-1 


7/30/90 



Application Programming Interface 


Ch. 4: Library Requests 


Notes • All definitions of constants (uppercase parameters) can be 

found in the files a:\include\ui.h and mainsym.h. 

I 

• The KEYS shown for each command are those keys that 
will return execution to the calling procedure. You must 
define the response to each of these keys. 

• When colors are used within the request, they are identified 
using the following numbering scheme shown in Figure 4.2. 


COLOR 

IDENTIFICATION 

BLACK 

‘O’ 

RED 

1 T 

GREEN 

‘2’ 

YELLOW 

' ‘3’ 

BLUE 

*4’ 

MAGENTA 

■5' 

CYAN 

‘S’ 

WHITE 

7’ 


Figure 4.2: Display Color Encoding 


Within this table, the right column is used as an entry to a 
request. Using the actual name of the color will cause an 
error. 
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Ch; 4: Library- Requests 


Application Programming Interface 


BOXJNPUT 


Description The request BOXJNPUT is used to create a list box of 

selections at run-time. This allows for dynamic creation of 
choices within a box. 

The command BOXJNPUT is similar to the command 
BOX_REQ. You must be familiar with that command before 
you use BOXJNPUT. 

The following keys are used to edit the fields: 

• CTRL A Append 

• CTRL I Insert 

• CTRL D Delete line 

Keys The following keys can be used to exit from the list selector: 

• ESC 

• CANCEL 

• GO 


Parameters The structure type BOXREQ is used to define the box. This is 

the same structure type used for the BOXJREQ command. 
The only difference between the two structures will be the 
event parameter. In this case it is set to BOXJNPUT. 

All of the other parameters are described in detail within the 
BOXJREQ command. The structure is as follows: 

typedef struct 


{ 


int 

event; 

int 

taskld; 

int 

box; 

int 

len; 

byte 

color; 

int 

col; 

int 

row; 

int 

clear; 

int 

choice; 

int 

maxRow; 

int 

frame; 

byte 

bcolor; 

byte 

rev; 

int 

lines; 

SCRAREA 

*p; 

int 

offset; 

int 

setRow; 

}BOXREQ; 
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An array of pointers, containing at least two entries, must be 
initialized before you can initialize a BOX_JNPUT. This can be 
done by calling fiilBoxArea<). 

The example shown on the following wiil illustrate. 


Return 

Structure 


The return parameter conf is of the type BOXCONF. This 
structure contains the information regarding the selection 
within the list selector, the keystroke used to exit the list, the 
current selection position on the screen and a pointer to the 
selected string. 

The structure is defined as follows: 

typedef struct 

int event; 
int exit; 
int choice; 
byte *str; 
int row; 

}BOXCONF; 

event BOX_CONF 

exit The key used to exit the list selector 
(GO, RTN, ESC, CAN, LEFT or RIGHT.) 

choice The number of the selected parameter where 1 is 
the first non-title string 

*str A pointer to the actual string chosen. 

row The row number on the screen. This defines where 
the selection is actually located. This value is 
useful in combination with setRow. 
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Example 


The example shown below illustrates the logic used to edit the 
contents of a list selector. Note that an entry can always be 
removed by the user by pressing CTRL-D. 

This example shows the editing of completely free format data 
(getsQ). This logic is normally replaced by some format 
specific to the application. 

For example, a string displayed within another list selector can 
be retrieved and copied into the edited list. Note that each 
string must be adjusted to be the same length. 


80XREQ my_box = {B0X_INPUT }, /‘initialized parameters*/ 

byte *rayBox[] = {"-This is the title", 

* End Str "}; 

fillBoxArea (&my_box, m'yBox); /‘in the beginning of the program*/ 


exit = FALSE: 
do 

{ 

userlnterf ace (&my_box, Sconf, dsp, box); 
switch (corif.exit) 

{ 

CNTRL_A: j 

CNTRL_I : positionCursor (conf. row, my_box.col); 

gets ' (conf . str) ; /’get an unformatted*/ 

fillToLength {conf. str, my_box.len) /* string*/ 

my_box .setftow = conf. row; /’make sure it has’/ 

my_box.off set = conf. choice; /‘the same length */ 

break; /*as other strings’/ 


ESC; 

CAN: fillBoxArea. (&my_box, 

exit * TRUE; 
break; 

GO: exit = TRUE; 

break.; 

} 

} 

while (’exit); 


myBox); /’reset contents*/ 
/* to original */ 

/•Exit by keeping */ 
/•editions made in*/ 
/• this session */ 
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BOX_REQ 

Description 


Keys 

Parameters 


A BOX_REQ is used to display a list of selections from which a 
choice can be made. The UP and. DOWN arrow keys are used 
to move from one choice to another within the box. When the 
list of choices is longer than the frame size, the list will scroll. 

This request returns a structure, type BOXCONF, as described 
below. This structure contains information about the selection 
made. 

Chapter 5 provides an example showing how this request is 
used to implement a pull down menu application. 


The following keys can be used to exit from a list selector: 

• GO • RIGHT 

• ESC ' « LEFT 

• CAN • RETURN 


The structure type BOXREQ is us^d to define the box. This 
includes information on the length of the text strings, the color 
the border, text and reverse video, the column and row of 
locations for the text strings, size and amount of interaction 
possible. The structure is defined as follows: 

typedef struct 


{ 


int 

event; 

int 

taskld; 

int 

box; 

int 

len; 

byte 

color; 

int 

col; 

int 

row; 

int 

clear; 

int 

choice; 

int 

maxRow; 

int 

frame; 

byte 

bcolor; 

byte 

rev; 

int 

lines; 

SCRAREA 

*p; 

int 

offset; 

int 

setRow; 

}BOXREQ; 


Each of these parameters are defined on the following page. 
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) 




) 


event BOX_REQ. 

taskld Reserved. Set to 0 

box The box identification number, n, where 

0 < n < NUM_OF_BOXES. 

Observe that each BOXREQ definition is associated 
with a unique box number. The recommended 
procedure is to increment the value for each box 
definition. 

len The length of the string to be displayed +1. This 

determines how the outline is drawn around the 
text. All strings to be displayed should be of the 
length = len (including the \0). 

color The color of the text, this is specified according to 
the Figure 4.2. 

col ■ The. starting column number for each text string. 

row The row number to position the first text string. The 
top line is in row 1 so begin with row’ 2 when using 
a frame. 

clear Determines if the area under the box will be erased 
before displaying. This is important with overlapping 
boxes. 

• TRUE erase area before displaying 

• FALSE don’t erase area before displaying 

(this can be a time saving selection.) 

choice Determines if the interface will wait for user input 
before returning to the application. 

• TRUE wait for user input 

• FALSE do not wait for user input. Return to 

the application immediately after 
displaying the list. See the function 
cSToggle{) for an example of this. 

maxRow Defines the number of rows that will be shown 
within the box and locates the the bottom border. 

Refer to the notes following these descriptions for 
. information on how this works with lines. 

frame A box can be bounded by a frame, and arrows on 
any of the sides. This parameter is used to select 
which portions of the border and which arrows will 
be displayed. 
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The following border and arrow selections are 
available: 


FRAME 

COMMANDS 

DESCRIPTION 

ARROW 

COMMANDS 

DESCRIPTION 

FRM 

A complete frame 

I ARS 

All four arrows 

TOPF 

Top of frame 

1 TAL 

Top arrow only 

BOTF 

Bottom of frame 

BAR 

Bottom arrow only 

RiGHTF 

Right side of frame 

RAR 

Right arrow only 

LEFTF 

Left side of frame 

LAR 

Left arrow only 

NOF 

No frame 

1 



Figure 4.3: Frame and Arrow Commands. 


Multiple commands can be combined using + . For 
example, to display a complete border with arrows 
on the left and right, enter FRM + LAR + RAR. 

bcolor The color of the border, specified according to 
Rgure 4.2. 

rev The color 'Of the selection highlight if it is enabled 
(see choice). It is specified according to Figure 
4.2. 

lines The total number of strings contained in the box. 
(Add two for the title and terminating line.) 

Refer to the notes following these descriptions for 
information on how this works with maxRow. 

*p This should always be set to NIL. It is initialized by 

the call to fillBoxArea(), getFileChoice() or 
gelBoxAreaQ. 

offset The line number of the selection currently 
highlighted. This refers to the line number within 
the box. It, is initialized to 0. 

Refer to the notes following these descriptions for 
information on how this works with setRow. 

setRow The position (row number on the screen) of the 
selection currently highlighted. This should be 
initialized to the same value as row. 

Refer to the notes following these descriptions for 
information on how this works with offset. 
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Notes: Some of the parameters seem to identify the same attributes. 

This section is meant to clarify those parameters and show 
how they work together to provide flexibility within the user 
interface. 


Initialization of a List Selector 

A list selector differs from other API requests in that it consists 
of two building blocks. First,, the BOXREQ structure itself, and 
secondly an array of pointers to strings that correspond to the 
possible selections within the list selector. The scrolling area 
within the BOXREQ (SCRAREA *p;) is initialized with these 
strings by using the function fHIBoxArea(). See the previous 
chapter for details. 

The array of pointers has the foildwing format: 

byte ‘example [] = {" TITLE STRING", 

" FIRST CHOICE", 

"SECOND CHOICE", 


" END STRING 

When using fil!BoxArea(), the parameter lines within the 
BOXREQ must be initialized to the exact number of strings as 
declared in the array of pointers. 

All strings except the TITLE STRING and END STRING are 
selectable. If a title and end string are not required in the list 
selector being defined, both strings can be initialized to an 
empty string This displays only the selectable strings. 

NOTE: All of the strings initialized within the array of pointers 

must be of the same length. 

If the selections are to be marked using the function 
cSToggle(), the first character in each selectable string should 
be a blank. 

Note: The functions getBoxArea() and addNewLine() can 
be used to build a list selector by adding one line, at a 
time to the end of the list. These functions are 
described in detail in Chapter 3. 
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maxRow vs. lines 

These parameters together define the size of the box and the 
number of fields to be 'displayed within the box. This is most 
easily seen by an example. 

The Session list selector shown here is 
made up of seven selectable strings and a 
title. The end string is an empty string 
To accomodate this list, lines should be set 
to nine (7 lines plus 2). This determines the 
total number of selectable strings including 
the title and terminating line. It does not 
determine maxRow. 


Displaying all of the choices may 
take up more space on the screen 
than allocated for this box. By 
setting maxRow to row +4, five 
rows of information are displayed 
at any time. 

The additional information is 
displayed by scrolling through the 
choices using the arrow keys. 


Session 
Cboica X 
Choice 2 
Choice 3 
Choice 4 


row 


maxRow 


Session 

> 

Choice 2 
Choice 3 
Choice 4 
Choice 5 
Choice 6 
Exit 7 


Choice 3 
Choice 4 
Choice 5 
Choice 6 
> Exit 7 


By pressing the down arrow three times, the 
title and first selections are scrolled out of 
the box and replaced with the additional 
selections. 

if the first string was originally placed in row 
2, Choice 3 is now in row 2 and Exit in row 6. 
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Returned 

Structure 


offset vs. setRow 

These parameters are used to redisplay a box with the 
highlight on the most recent selection. This is done by 
combining a location within the list ( offset ) and the actual 
location on the screen {setRow). 

Another example will illustrate. 


Session 

> flllfil :.i: 

Choice 2 
Choice 3 
Choice 4 


The- box is initially displayed with the first 
selection highlighted. This is set up as: 

my_box.offset = 0 
my_box.setRow = row 


You can then move down to Choice 3 and 
select it. 

To automatically highlight Choice 3 when the 
box is redisplayed, set: 

my_box. offset = conf. choice 
my_box. setRow = conf. row 

These, parameters are located within the 
structure BOXCONF. This is the information 
returned by the function as defined below. 

Refer to the function csTogg!e{) for an 
example of how this is used. . 


Session 
Choice 1 
Choice 2 
> Cfwrca- 3 
Choice 4 


The return parameter conf for a BOX_REQ is of the type 
BOXCONF. This structure contains the information regarding 
the selection within the list selector, the keystroke used to exit 
the list, the current selection position on the screen and a 
pointer to the selected string. 

The structure is defined as follows: 

typed ef struct 

{ 

int event; 
int exit; 
int choice; 
byte *str; 
int row; 

}BOXCONF; 
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event BOX_CONF 

exit The key used to exit the list selector 

(GO, RTN, ESC, CAN, LEFT or RIGHT.) 

choice The number of the selected parameter where 1 is 
the first non-title string 

*str A pointer to the actual string chosen. 

row The row number on the screen. This defines where 
the selection is actually located. This value is 
useful in combination with setRow. 


Example The following example sets up a list of choices (Box1[]) with 

LIST 1 as the titles and Choice 1 initially highlighted. The 
outline is magenta and the text- is yellow. 

Since maxRow - row + 2 < lines (5-2 + 2 <7), the list wiil 
scroll. 

#define B0X_1 1 

byte *8oxl[] = 

{"LIST 1 
"Choicel ", 

"Choice2 ", 

"Choice3 
"Choice4 
"Choices ", 

/‘The end string is the empty string*/ 

BOXREQ box_l = 

{BOX-REQ, 0, 80X-1 , 11, '3', 2S, 2, TRUE, 

TRUE, 5, FRM, 'S’, 'S’, 7, NIL, 0, 2}; 

The call to the function is made as follows: 

fillBoxArea (&box_l, Boxl); /» Initialize box to contain strings*/ 


userlnterface (3box_l, &conf, dsp, box); 
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DSP_REQ 


Description 


This command is used to display text within a window. The 
type of window, defined by WINDOW_REQ, determines how 
the command is used.- The window must be initialized using 
the WlNDOW_REQ command before using DSP_REQ. Refer 
to WINDOW_REQ for a description of the different types of 
windows. 

Note that this command does not redisplay the border around 
the text. 


Keys 

Parameters 


None 


The structure type DSPREQ is used to specify the information 
to be displayed, it'is defined as follows: 

DSPREQ ■ This identifies the window to contain the 
display and a pointer to the text to be 
displayed. 

typedef struct 

■ ■ { 

int event; 

int taskld; 
int window; 
byte *text; 

}DSPREQ; 


event DSP_REQ 

taskld This bit is reserved. It is always set to 0. 

window The window identification number, where 
0 < n < NUM_OF_WINDOWS 

“text If the window is defined as SCROLLING, then this is 
the pointer to the string to be displayed. 

If the window is defined as STATIC, with the output 
field in the WINDOW_REQ defined as NIL, then the 
pointer is to a structure of the type FIELD. 

Otherwise, with the window defined as STATIC and 
the output field defined to point at a F1ELD_SEQ,- 
this parameter is set. to NIL. 
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Example 


The three examples that follow illustrate using the command 
DSP__REQ. 

The first example illustrates a window type defined as 
SCROLLING. 

^define. TE$T_WIN 1 

WINDOWREQ- mywindow = {WINDOW_REQ, TEST_WIN SCROLLING, ...}, 

byte testStr[] = "Test QSP^REQ" ; 

DSPREQ myOSP = (DSP_R£Q, 0. TEST_WIN, NIL}; 

userlnterface {SmyWindow, &ch, dsp, box); /*byte ch*/ 


my0sp.txt. = testStr; 

userlnterface (SmyOsp, &ch, dsp, box); 


The second example illustrates a STATIC window with the 
output field defined as NIL. 

^define TES7_WIN 1 

byte testStrf] = "Test DSP_REQ“; 

FIELD errStr = (10, 1, NIL}; 

DSPREQ myOSP = {DSP_REQ, 0, TEST_WIN, (byte*)&errStr}; 

WINDOWREQ myWindow = {WINDOW_REQ, TEST_WIN STATIC NIL}; 

userlnterface (&myWind.ow, &ch, dsp, box-); /*byte ch*/ 


errStr. str = testStr; 

userlnterface (&myDsp, Sch, dps, box); 


The third example illustrates a STATIC window with the output 
field set as a pointer to FIELD_SEQ. The DSP_REQ redisplays 
only the F1ELD_DEF entries with the change flag set to true. 
When the DSP_REQ is completed, ail change flags are set to 
false. 


^define TEST_WIN 1 

FIELD_QEF el * { }; 

FIELDJJEF ■ e2 = { }; 

FIELD_SEQ ee = {&el, &e2, NIL}; 

DSP_R£Q myDsp = {DSP_R£Q, 0, TEST_WIN, NIL}; 

WINDOWREQ myWindow = {WINDOW_REQ STATIC &ee} ; 

userlnterface (SmyWindow, &ch, dsp, box); /*byte ch*/ 


i=0; . . 

while (ee.f[i]) ee.f [i++]-> changed = TRUE /* set all changed 

flags to TRUE, in other situations 
you may only want to set the flags selectively */ 
userlnterface (&myOsp, &ch, dsp, box); 
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ERASE_FiELD 

Description 

Keys 

Parameters 


This is a request to erase a specific field from a window. This 
will erase both the description and the associated value. 

This command is valid only for a STATIC window request with 
the output field set to FIELD_SEQ, Refer to the command 
WINDOW_REQ for details on this type of window. 

The structure type F1ELD_DEF is defined with the command 
W1ND0W_REQ. The changed field within that structure must 
be set to ERASE_FiELD for this command. Once the 
command is executed, the changed flag is set to false. 


None 


The structure type. ERASEFIELD is used to specify the window 
to be erased. It is defined as follows: 


ERASEFIELD This specifies the type of request and window 
identification. 

typedef struct 

{ 

int event; 

int taskld; I 

int window; 

JERASEFIELD; 

event ERASE_FIELD 

taskID This bit is reserved. It is always set to 0. 

window The window identification number, where 
0 < n < NUM_OF_WINDOWS 
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Example 


This example initializes a window with three sets of fields, 
each a description and a value. The window is identified as 
window #5. Any of the fields (eO, el or ez) which have 
FIELD_DEF.changed set to ERASE_FIELD, will be erased 
when an ERASE_FIELD request is initiated. 

FIELD-DEF eO = 

{TRUE, 5, 7, "Desc. fieldl", 6, 25,init. valuel}; 

FIELD-DEF el = 

{TRUE, 6, 7, "Desc. field2", 6, 25,init. va1ue2}; 

FIELD_DEF ez = 

{TRUE, 7, 7, "Desc. fie1d3", 7, 25,init. va1ue3}; 

FIELO-SEQ ee = { &e0. Set, &ez, NIL}; 

WINDOWREQ dsp_win = 

{WINDOW-REQ, 0, 5, STATIC, 40,60, ' 3 ‘ , 5, 5, 

FALSE, 10, 20, FRM, FALSE, '5', inoTitle, See }; 


The FIELD— DEF structure for field ez is then changed to 
indicate that it will be erased and the ERASE_FIELD structure 
set up. 


ez. changed = £RASE_FIELD 

ERASEFIELD era = {ERASE_FIELD, 0, 5 }; 

userlnterf ace (&dsp_win, &ch, dsp, box); 


userlnterface (Sera, Sch, dsp, box); 
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ERASEB_REQ 

Description 

Keys 

Parameters 


Returned Values 
Example 


This requests that an entire list box be erased from the 
screen. 


None 


The structure required for this request is of the type 
ERASEREQ. it is defined as follows: 

typedef struct 

{ 

int event; 
int taskld; 
int box;. 

}ERASEREQ; 


event ERASEB_REQ 

taskld This bit is reserved. It is always set to 0. 

box The box identification number, where 

0 < n < NUM_OF_BOXES 


None 


This example displays and erases a box. 

^define MY_B0X 1 

BOXREQ myBox = (BOX_REQ, 0, MY_B0X , ...}; 

ERASEREQ eraMyBox = {ERASEB_REQ, 0, MY_80X}; 

userlnterf ace {SmyBox, Sconf, dsp.'box; 
userlnterf ace (SeraMyBox, Sconf, dsp, box}; 
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ERASEW_REQ 


Description This requests that a window be erased from the screen. 


Keys None 


Parameters The structure required for this request is of the type ERASERQ. 

It is defined as follows: 

typedef struct ■ 

i 

mt event; 
int taskld; 
int box; 

JERASEREQ; 


event ERASEW_REQ 

taskld This bit is reserved. It is always set to 0. 

box The' identification number for the window, where 

0 < n < NUM_OF_WINDOWS 


Returned Values None 


Example This example displays and erases a window. 

^define MY_WINDOW 1 

WINDOWREQ myWindow = {WIN00W_R£Q, 0, MY_WIND0W, ...}; 
ERASEREQ eraMyWindOw = {ERASEW_REQ, 0, MY_WIND0W}; 


userlnterf ace (SmyWindow, Sconf, dsp, box; 


userlnterf ace (SeraMyWindow, &conf, dsp, box}; 
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INPUT_REQ 


■ Description This command is used to display a sequence of fields to be 

edited, for example, configuration parameters. 

The fields can be different types, integers, strings, hex or 
binary. The min & max parameters of the INPUT^FIELD^TYPE 
are used to limit the range of values that can be entered for a 
particular field. 

Use the arrow keys, T l-**-, to move around between the 
fields. 

The fields making up the sequence are numbered. The arrow 
keys are set to these numbers in order to control the 
sequence the fields are selected in. 

The following keys can be used during runtime operation to 
modify the field values. 

• CTRL-N Go to the next field 

• CTRL-P Go to the previous field 

• CTRL-1 Insert mode (Default mode is overwrite) 

• CTRL-D Delete to end of line 

• CTRL-A ■ Go to the beginning of the line 

• CTRL-E Go to the end of the line 

• RETURN Go to the next field 

• Space Bar Toggle between preset values 

A unique prompt can be associated with each input field. This 
text is displayed, in a position specified within the request, 
each time the cursor is positioned at that field. The prompt 
text is typically used to tell the user the permitted range for a 
value. 

Messages indicating the current mode, either insert or blank 
for overwrite, or an error when a value outside of the specified 
range are displayed. These are located as specified in the 
INPUT_REQ structure. 

This field does not display a frame around the input 
parameters. To display a frame, initiate a static 
WINDOW_REQ without fields before calling 1NPUT_REQ. 


) 
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Keys 


Parameters 


The recommended strategy to use this command is to define 
a structure type corresponding to the input field sequence 
defined for the screen. Deciare two structures of this type. 
The first will be used as the configuration description for the 
application and the second to be used as a work area for the 
1NPUT_REQ. tf the input fields for the 1NPUT_REQ definition 
are set to point at entries in the work structure, the following 
logic is both efficient and convenient. 


SCREEN_OESR_TYPE param, paramWork ; /* Structure- describing screen */ 

INPUTREQ mylnput = { } /’initialized parameters*/ 

paramWork = param; . /* assign the work structure the values 

of the current configuration. */ 
userlnterface {Smylnput, SresultChar, dsp, box); 

if (resultChar == GO) /* Use the parameters only if the user*/ 

param = paramWork; /* decided to save the configuration */ 


The following keys can be used to exit from or cancel the 
command: 


• CAN 

• ESC 

• GO 


There are three types of structures required to initiate an 
INPUT_REQ. They are defined on the following pages. 

This command uses different color definitions than those 
previously defined (Figure 4,2). These are shown in Figure 
4.4. Refer to the examples at the end of the command to see 
how these are used. 



Figure 4.4: i 

Color Definitions for 1NPUT_REQ 
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INPREQ 


event 

taskID 

*fp 

fi 

*i_color 

*t_color 

*c_color 

c_row/ 

c_col 

*s_color 

s_row/ 

s_col 


This defines the location and color of 
parameters displayed, the prompt text and 
other messages. 

typedef struct 

{ 

int event; . 


int 

taskld; 

INPUT. 

_FIELD_TYPE 

byte 

fi; 

char 

i_color; 

char 

*t_color; 

char 

*c_color; 

byte 

c_row; 

byte 

c_col; 

char 

,, s_color; 

byte 

s_row; 

byte 

s col; 

}INPREQ; 


1NPUT_REQ 

This bit is reserved. It is always set to 0. 

A pointer to the INPUT_F1ELD_TYPE structure. 

An index initializing the offset to the first 
selectable field. Set to zero if the cursor is to be' 
on the first field when the INPUT_REQ is called. 

The color of the value field, specified according 
to Figure 4.4. 

The color of the description field, specified 
according to Figure 4.4. 

The color of the help prompt, specified 
according to Figure 4.4. 

The location of the help prompt. 

(row and column number) 

The color of the insert mode and invalid value 
messages, specified according to Figure 4.4. 

The location of the insert mode and invalid value 
message (row and column number) 


TEKELEC 


4-21 


7/30/90 



Application- Programming Interface 


Ch. 4: -Library Requests 


iNPUT_F!ELD_TYPE 

This structure defines a field on the screen. 
This includes the position on the screen, the 
■ - title and input value, the field type and the 
allowed range. 

To define a sequence of fields, an array of 
these structures is declared. The last entry of 
this array is defined as {0, 0, 0, 0 ,0 , ...} or 
zero for all values. 

The arrow keys are set to go from field to 
field. 

typedef struct 

( 

byte row; 
byte column; 
byte len; 
byte *buff; 
byte type; 

byte If flag; 

byte arrow_flag; 
byte c_row; 
byte c_column; 
byte *c_text; 
byte *c_buff; 
byte up; 
byte down; 
byte right; 
byte left; 
byte num_chk; 
unsigned int min; 

unsigned int max; 

FKEY_FIELD_TYPE *fk_ptr; 

} 1NPUT_F1ELD_TYPE; 


row/ The screen location for the input field 

column (row and column number) 

len The maximum number of characters for input 

on the screen. 

• For string input, this is equal to. the string 
length. 

• For integer input, where no range checking 
is configured, it corresponds to the 
maximum integer value. 

’buff A pointer to the area where the result will be 

stored. 
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j 


))' 


type 


lf_fiag 


arrow_flag 


c_row/ 

c_column 

*c_Jext 
. *c_buff 
up 

down 

right 

left 

num__chk 


min 

max 

*fk_ptr 


The input data type, where: 

0 string 

1 byte or int 

2 hex {returns an ascii hex string) 

3 binary (returns an ascii binary string) 

Set to 1 to insert a line feed before the (\0) 
field terminator. This allows for easier file 
retrieval, for example, fgetstring() from the 
standard C library. 

Set to 1 to display a red arrow pointing to the 
selection. Otherwise, set to 0. 

Fields that toggle between values are 
automatically marked with a red arrow. 

The screen location for. the field title 
(row and column number) 

Pointer to the field description or title text 
string 

Pointer to the help field text string positioned 
through INPREQ (prompt text). 

The next field in response to an up arrow 

The next field in response to a down arrow 

The. next field in response to a right arrow 

The next field in response to a left arrow 

Set to 1 to check that the input is within a 
specified valid range. This, uses the next two 
parameters. 

A minimum value for the valid range 
A maximum value for the valid range 

• A pointer to the FKEY_FIELD_TYPE, if 
used. These values are a fixed set, 
defined by this structure array. The red 
arrow is automatically displayed. With this 
selection, the user toggles between preset 
values with the space bar. 

• Set to NIL if it is not used. 
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FKEY_F1ELD_TYPE 

This structure defines the preset acceptable 
values for a field. 

To set a sequence of values, define an array 
of these structures with the last entry equal to 
{Oxff, NIL}; This will define the end of 

tne value options. 

typedef struct 

byte fkey; 
byte *disp_text; 
byte “value; 
byte “link; 

}FKEY_FIELD_TYPE; 


fkey 


*disp_text 


“value 


link- 


This is a flag indicating either the last entry, or 
an additional value option. 

• ON display the text string 

• Oxff end of toggle fields. 

The text or description of the field. Note that 
each entry must be the same length. 

This is the text seen when the value is toggled 
to his choice. This entry can be symbolic or 
numeric, for example “ON” or “1”. 

The actual value associated with this entry. This 
value is specified: as a string and converted 
according to the type of field. 

A pointer to a choice within another toggle field 
to be blocked as a result of this choice. 

This field is set to NIL is no fields are to be 
blocked. 
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Returned Value 


Example 


The key used to exit the input screen is returned in the byte 
sized parameter, ie an unsigned character. 

For example, in the example shown on page 4-20, the return 
value declaration would be: 

byte resultChar; 


The following example initializes a window with five fields and 
Jheir associated help messages. Four of the five fields can be 
eldited by entering a number within the range provided. The 
field Encode is changed by pressing the space-bar to toggle 
between the choices NRZ and NRZI. 

F ICE Y FI ELD TV P E encode-f key[] - 

{ | 

{ON, "NRZ VO". NIL}, {ON , "NRZI" , " 1" , NIL) , 

{Oxff, NIL} 

}; 

INPUT_FIELD_TYPE conf 2_f iel ds[] = 

{ • 

{10, 16,3,&irWoric.tei , 1,0,0, 10,5, "TEI 

"TEI-COM" , 4, 1,4, 3, 1,0, 127, NIL), 

{12, 16,2,&irWork.sapi , 1,0,0, 12., 5, "SAPI 

"SAPI_C0M“ , . 0,2, 0,4, 1,0,63, NIL}, 

{14, 16,1, Si rWork .encode , 1,0,0 , 18,5, "Encode : ” , 

"ENC-COM”, 1,3, 1,3, 0,0,0, encode_f key} , 

{10,38, 3 ,&i rWork . n201 , 1,0,0, 10,28, “N201 

"N201_.COM", 2, 4, 0,4, 1 , 1 , 512 , NIL} , 

{ 12 , 38 , 4 , & i rWor k . n 20 0 ,■ 1,0,0, 12,28,”N200 

"N200—C0M” , 3, 0,1,0, 1 , 1 , 9999 , NIL} . 

{0,0, 0,0,0, 0,0, 0,0, 0,0,0} 

}: 


INPREQ confZ_input * 

{ INPUT-REQ, conf2_f ields, 0, CYAN, YELLOW, GREEN, 20, 23, 

MAGENTA, 20, 5};' 
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REL_REQ 

Description 

Keys 

Parameters 


Example 


This request is used to de-allocate the memory set aside for a 
window and releases the associated window number. This 
should be done when a window wiii not be used again. 

You can then reinitialize the window number with new 
attributes. 


None 


One structure is required to initiate a REL_REQ. It is used to 
identify the window that will be released. It is defined as 
follows: 

typedef struct 

{ 

int event; 
int taskld; 
int window; 

}RELREQ; 


event Defines the type of request, REL_R£Q 

taskld This bit is reserved. It is always set to 0. 

window The window identification number, where 
0 < n < NUM_OF_WlNDOWS 


RELREQ exmp3 {RE! REQ, 0, WtNDOW_NUM}; 

userlnterface {&exmp3, NIL, dsp, box); 
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WINDOW. 

Description 


Parameters 


REQ 


The command WINDOW_REQ can be used in two ways, it 
can be used to initialize a window which will display 
information or it can display a frame around an input request. 

There are three types of windows defined through 
WINDOW_REQ. 

• SCROLLING 

A scrolling window displays information each . time a 
DSP_REQ is made. The window is a fixed size, With the 
information scrolling either forward, with new information 
added at. the bottom of the list, or backward, with new 
information added at the top. 

• STATIC without field sequences 

A static window displays information at a fixed location 
within a window. The information does not remain in an 
allocated memory position, and requires a subsequent 
DSP_REQ to redisplay. This can be used to draw a frame. 

• STATIC with field sequences 

A static window with field sequences displays information 
from an allocated memory position to a fixed location within 
a window. A field sequence is made up of several titles 
and values. 


The parameters for the W!NDOW_REQ are incorporated into 
four structures. Each of these structures are shown below 
with a brief description of each of the internal parameters. 
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WiNDOWREQ This identifies the window and sets up the 
basic attributes that determine how the 
window will be displayed. 


typedef struct 

{ 

int event; 

int tskld; 

int window; 

int type; 

int len; 

int strLen; 

byte color; 

int col; 

int row; 

int clear; 

int minRow; 

int maxRow; 

int frame; 

int back; 

byte bcoior; 

FIELD- Title; 

FIELD ‘output; 

}WINDOWREQ; 


event The event defines the type of request, in this 

case.W!NDOW_REQ 

taskld This bit is reserved. It is always set to 0. 

window The window identification number, where 
0 < n < NUM_OF_W!NDOWS 

type Either STATIC or SCROLLING, where; • 

• STATIC 

The information is displayed in a fixed location 
within the window as defined by the DSP_REQ 
made to this window number. This can be 
done with or without field sequence, where a 
field sequence is a list of titles, associated 
value fields and a flag indicating that the field 
has been displayed. 

> With a Field Sequence 

The field sequence is located in a storage 
area containing all of the information 
displayed within this window type. The 
contents can be modified before they are 
displayed. They are displayed using a 
DSP_REQ or WINDOW_REQ. 
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> Without a Field Sequence 

With this type of window, no storage area 
is allocated. The location of each string is 
defined by the DSP_REG. Once a string is 
erased, it cannot be redisplayed without a 
new DSP_REQ. This window type can be 
used to display a frame. 

• SCROLLING 

Each string of information is displayed either 
at the top or bottom of the existing 
information. This is determined by the 
parameter back. Note that all strings will be 
visible until the window frame is full. 

TRUE Each new line is added to the top 
of the list, pushing existing 
information out of the bottom of the 
window. 

FALSE Each new' line is added to the 
bottom of the list, pushing existing 
information out of the top of the 
window. 

With the first WlNDOW_REQ, an area in 
memory is allocated, corresponding to the 
size of the window. For subsequent calls to 
WINDOW_REQ for this window number, the 
complete contents of this area is displayed. 

The size of the scroll area, or window, is 
determined by the number of lines in the 
window description and the length of a 
displayabie string. The length of the 
displayable string is equal to the parameter 
strLen, the length of the window ( len ) plus the 
number of characters required by an optional 
escape sequence. 

len This determines the actual width of the window. 


strLen For STATIC windows, this should be set to 0. 

For SCROLLING windows, strLen is set to the 
parameter len plus the number of non-printing 
characters added to a string within this window. 
This, for example, allows you to change te color 
in the middle of a string. 

color The color of the text displayed within a window, 

specified. according to Figure 4.2 

col, row The first row below the window frame and the first 
column to the left of the left frame. 
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clear 


minRow 


maxRow 

frame 


Determines if the area under the window will be 
erased before displaying. This is important with 
overlapping windows. The top window must 
erase the area before displaying to avoid overlap. 

* TRUE erase area before displaying 

• FALSE don’t erase area before displaying 

(This can save time) 

This parameter applies to scrolling windows only. 
If specifies the upper boundary of the scrolling 
area for a forward scrolling window, the lower 
boundary for a backward scrolling window. 

This, combined with maxRow, defines the area of 
the window and screen that will contain scrolling 
data. 

The last row above the lower frame edge. 

A window can be bounded by a frame, with 
arrows on any of the sides. This parameter is 
used to select which portions of the border and 
which arrows will be displayed. 

The following border and arrow selections are 
available: 


FRAME 

COMMANDS 

DESCRIPTION 

ARROW 

COMMANDS 

DESCRIPTION 

FRM 

A complete frame 

ARS 

All four arrows 

TOFF 

Top of frame 

TAL 

Top arrow only 

BOTF . 

Bottom of frame 

BAR 

Bottom arrow only 

RIGHTF 

Right side of frame 

RAR 

Right arrow only 

LEFTF 

Left side of frame 

LAR 

Left arrow only 

NOF 

No frame 




Figure 4.5: Frame and Arrow Commands. 


Multiple commands can be combined using +. 
For example, to display a complete border with 
arrows on the left and right, enter 
FRM + LAR + RAR. 
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back 

bcoior 

“title 

“output 


FIELD 


row 

/col 

*str 


This defines the direction of scrolling when the 
window type is SCROLLING. With other types of 
windows, it has no effect. 

TRUE scroll backward 
FALSE scroll forward 

The color of the outline,'- specified according to 
Figure 4.2. 

A pointer to the structure FIELD described below 
which can be used to initialize the title of a 
window. This title is redisplayed each time the 
window is redisplayed. 

This is used with static windows with field 
sequences only. It uses a FIELD_SEQ structure 
containing a sequence of F1ELD_DEF structures, 
to display a window of information. 

■ For other window types, this field must be set to 
NIL 


This contains the location and text that make up 
the title of a window. 

typedef struct 

{ • 

mt row; 
int col; 
byte *str; 

} FIELD; 


The location of the text string containing the title. 
{Row and column information) 

A pointer to the text string 
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F1ELD_DEF typedef struct 

int changed; 
int rowT; 
int colT; 
byte "title; 
int rowO; 
int colO; 
byte "output; 

} ' FIELD_DEF; 


changed This parameter, set to TRUE, indicates that the 
information for this field wifi be redisplayed when 
an additional WINDOW_REQ or a DSP_REQ is 
initiated on this window. 

Note that this same structure is used to erase a 
field within the window simply by changing this 
parameter to ERASE_FIELD. 

rowT/ The screen position of the title of the field 
colT description. (Row and column number.) 

"title A pointer to the text string containing the field 

title. 

rowO/ The screen position of the field value. 
coiO (Row and column number.) 

"output A pointer to the text string containing the value 


FlELD_SEQThis contains pointers to the series of F1ELD_DEF 
structures making up a static window. Note that 
a field sequence must be terminated with NIL. 

typedef struct 

F1ELD_DEF *f[MAX_FIELDSj; 

> F!ELD_SEQ; 

*f [MAX FIELDS] This contains the sequence of FIELD_DEF 

strings to be set up. 
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Examples 


The foliowing examples illustrate the use of WIND0W_REQ. 
The first sets up a static window, the second, a scrolling 
window. 

Example T 

The first example sets up a static window with two field 
definitions in a field sequence. The outline of the box will be 
magenta and the text yeliow. ■ 

FIELD Conf2Titte = {8, 13, "EXAMPLE 1"}; 

FIELD-DEF eO. = 

{TRUE . 5, 7," MESSAGE:'* , 6, 16," "}; 

FIELD-DEF el = 

{TRUE, 5, 40, "NAME:", 5, 47," '*}; 


FIELD-SEQ exl = { &e0, Set, NIL); 


WINDOWREQ conf2_win = 

{WINDOW-REQ, 1, STATIC, 44,60, '3', 3, 8, 

TRUE, 4, 20, FRM, FALSE, 'S’, &conf2Title, &exl }; 

Note: The output fields are initialized to blanks. They can 

be initialized to point to anything. 


Example 2 

The second example sets up a scrolling window with a title. It 
receives the text from a DSP_REQ which is not shown. 

The initial DSP__REQ displays the text on line 10 (min Row). 
Each successive DSP_REQ displays the test on lines 11, 12, 
13 and so on to line 20 {maxRow). Once line 20 is reached, 
further use of the DSP_REQ scrolls the text up and displays 
the new text on line 20. 

The outline of the box is white and the text is green. 

FIELD Title2 = {3, 30, "EXAMPLE 2"}; 

WINDOWREQ 6sp_win = 

{WIN0OW_REQ , 2, SCROLLING, 71,60, r 2', 5, 6, 

FALSE, 10, 20, FRM, FALSE, '7', 4Tit1e2, NIL); 
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Chapter 5: 

APPLICATION PROGRAMMING INTERFACE 
EXAMPLES 


Introduction 


There are three examples provided with the application 
programming interface, each illustrating a different aspect of 
the interface. These examples, including 


Section 5.1: Example 1, Pull Down Menu Logic 

Seption 5.2: Example 2, Parameter Input 

Section 5.3: Example 3, Listing Files from a Directory 


A sample display and brief description of each of the 
examples is provided at the beginning of the- associated 
section. 
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Introduction 


EXAMPLE ONE: 

PULL DOWN MENU LOGIC 


This appendix contains the files for example 1 . This example 
is made up of three files: 

• Select.c 

• uitab.c 

• uitab.h 

This example is composed of 5 boxes or list selectors. These 
provide the menu strip along the top edge and the four pull 
down menus. 

A window, as shown in Figure 5.1-1, is displayed when a 
selection if made from one of the boxes. 




NTTE~j 


SESSION 

>Load ' 
Save 
Exit5 


Menu2 


Menu3 


Menu4 



Figure 5.1-1: Example 1 
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File name: select. e 

Description: Display four list boxes to choose from. Once a 

selection has been made, snow the string and choice 



number . 



Version 

Date 

10 

Comment 

1.0 

030790 

RHT 

Created . 


^include "mainsym.h" 
#include "ui.h" 
^include "uitab.h' 1 


mai n( ) 

{ 

BOXCONF conf ; 
int i; 


/« INITIALIZE MENU SYSTEM V 



initUI{dsp,box,&error_win,NUM_OF_WINDOWS,NUM_OF_BOXES) ; 

/« MOVE STRING FIELDS INTO THEIR ASSOCIATED ARRAYS */ 




1 * 0 ; 

while (fil1boxes[i].box) { 

fillBoxArea(f i 11 boxes [i]. box, f illboxes[i], 1 1st); 
i++; 

} 

* * 

/* DISPLAY THE OPTIONS HEADERS ONLY */ 

/«««*«*«**«*•**«»•****«-****■)!**•**•«**/ 

userInterface(&box_Titles,&conf , dsp.box) ; 
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/**•****■«*«»***** *« »***«****•»*******«««•*«*«***«** »««**«*/ 

/« DISPLAY EACH LIST BOX UNLESS ESC OR CANCEL IS SELECTED */ 

i=0; 

for(;;) { 

a11_box[i].box->event = BOX_REQ; 
all_box[i].box->choice - TRUE; 
userlnterf ace(al1_box[ i ] .box, Scon f, dsp, box) ; 
al l_box[ i ] . box->event = ERASEB^REQ; 
userlnterface( al l_box[i].box,Sconf ,dsp,box) ; 
userlnterface(al l_box[4] .box, NIL, dsp, box); 
swi tch( conf . exit ) { 


/* init •• req. type */ 
/* set re-display */ 

/* display list box */ 
/* set erase flag */ 

/* erase 1 ist box */ 

/* display titles */ 


t 


GO TO THE NEXT LIST BOX, ERASE THE WINDOW 
AND RESET THE HIGHLIGHT BACK TO CHOICE 1 


/•*****•************************««********«***/ 

case GO; 

case RIGHT: if(i++ > 2) i = 0; 

cfiOice_win. event = ERAS£W_REQ; 
userlnterf ace(&choice_win, NIL, dsp, box) ; 
all J3ox[i].box->offset = 0; 
all_box[i].box->setRoi* = 2; 
break; 


I/,,..,.,.,,. 

/* GO- TO THE PREVIOUS LIST BOX, ERASE THE WINDOW */ 
/• AND RESET THE HIGHLIGHT BACK TO CHOICE 1 */ 



case LEFT: if(i — == 0) i = 3; 

choicejein. event = ERASEW_REQ; 
userInterface(&choice_win,NIL, dsp, box) ; 
al1_box[i].box->offset = 0; 
all_box[i].box~>setRow = 2; 
b reak ; 




/• CALL THE APPROPRIATE FUNCTION' AND SET */ 

/* THE HIGHLIGHT TO THE CHOICE MADE */ 

* 

case RTN: ( "al ]_box[i].f unc)(conf .choice, conf . str) ; /» handle_boxN »/ 
all_box[i ] :box->of f set = conf .choice; /* highlight the */ 
all_box(i ] .box->setRow - conf. row; /* selec. position */ 
break; 


/* | RESET AND CLEAR THE SCREEN, •/ 
/* THEN EXIT THE PROGRAM */ 


case ESC: 
case CAN; 

default: end_program( ) ; 

} 

} 

} 
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/• EACH OF THE FOLLOWING FUNCTIONS ARE IDENTICLE. THE ONLY REASON THEY 
ARE PRESENT IS TO SHOW HOW 4 SEPARATE FUNCTIONS CAN BE ORGANIZED AND 
ACCESSED. EACH LIST SOX AND SELECTION MADE WITHIN THE LIST BOX, IN 
AN ACTUAL APPLICATION, WILL SE HANDLE DIFFERENTLY. 

•/ 


/* 

* Display a window containing the string and choice number selected. 
V 

hand1e_boxl(choice,pstr) 
int choice; 
byte *pstr; 

C 1 1 

if (choice 3) end_program( ) ; /* exit program */ 

«•••••»..*• »»»»•»./ 

/* SET THE STRING AND CHOICE NUMBER V 

* 

Choice_Conf .title = pstr; 

*Choice_Conf .output = choice + 0x30; i 

I 

/«***»* 4 »*«*«********/ 

/* DRAW THE OUTLINE V 

choice_win .event = WINDOW_REQ; 
j userlnterf ace(&choice_win ,NIL,dsp , box ) ; 



/* INSERT THE TEXT INTO THE WINDOW */ 

choi ce_win. event = DSP_REQ; 

Ch_C.f[0]->changed = TRUE; 
userlnterf ace(&choice_win ,NIL,dsp ,box ) ; 

} 
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/* 

* Display a window containing the string and choice number selected. 

*/ 

handle_bDx2( choice, pstr) 
int choice; 
byte *pstr; 

{ 

* »»<*«*../■ 

/* SET THE STRING AND CHOICE NUMBER */ 



Choica_Conf . title = pstr; 

*Choice_Conf .output = choice + 0x30; 

I* DRAW THE OUTLINE */ 

/ **«*«•*••« ********* • • 

Choice_win .event = WINDOW_REQ; 
user!nterface(&choice_win,NIL,dsp,box) ; 



/« INSERT THE TEXT INTO THE- WINDOW */ 

choice_win. event = DSP_REQ; 

Ch_C.f[0]->changed = TRUE; 
userInterface(&choice win,NTL,dsp,box) ; 

} 


/• 

* Display a window containing the string and choice number selected. 

*/ 

handle_box3( choice, pstr) 
int choice; 
byte *pstr; 

{ 

/ 

/* SET THE STRING AND CHOICE NUM8ER •/ 



Choice_Conf .title = pstr; 

*Choice_Conf .output = choice + 0x30; 

.......MM.../ 

/* DRAW THE OUTLINE */ 



choice_win. event .= WINDOW_REQ; 
userInterface(&choice_win,NIL,dsp ,box) ; 



/* INSERT THE TEXT INTO THE WINDOW */ 

choice_win. event = DSP_REQ; 

Ch_C.f[0]->changed = TRUE; 
userlnterf ace(&choice_win,NIL,dsp , box) ; 

> 
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/* 

* Display a window containing the string and choice number selected. 

»/ 

hand le_box4( Choi ce.pstr) 
int choice; 
byte *pstr; 

{ 



/* SET THE STRING AND CHOICE NUMBER •/ 

yt»l*t«a«l*«***9«»»**9«*t*<****«»S«f •/ 

Choice_Conf .title » pstr; 

*Choice_Conf .output = choice + 0x30; 

/* DRAW THE OUTLINE V 

,,,. 4 ...,/ 

choice J*ifl. event = WINDOW_REQ; 
userInterface(&choice_win,NIL,dsp,box) ; 

/» INSERT THE TEXT INTO THE WINDOW V 

y»**«t*a*4«C4e*i**4f*44«*M44****«««e/ 

choice_win .event = DSP_RE-Q; 

Ch_C.f[0]->changed = TRUE; 
userInterface(&choice_win,NIL, dsp.box); 

> 


end program( ) /* exit the program */ 

{ 

printf (RESET) ; 
printf (CLEAR); 
enablecur(_stdvt); 
exit(0) ; 

} 
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File name: 

uitab. c 




Descri pti on : 

Initialize all 

user interface windows and boxes. 


Version 

Date 

ID 

Comment 


1.0 

*************** 

030790 

RHT 

****** 

Created. 


^include "mainsym. h" 

#include "ui.h" 

#include "uitab.h" 

DISPLAY dsp[NUM_OF_WINDQWS] ; /’System configuration. */ 

BOX box[NUM_QF_BOX£S] ; /’System configuration. */ 

/* DISPLAY ENTIRE BOX OF CHOICES */ 

y... ....... ............. 

byte *Boxl[] = 

{"SESSION 

"Load 

"Save 

"Exit5 

H 111 , 

/ » 

byte *Box2[] = 

{"MENU2 ", 

"Choicel " , • 

"Choice2 ", 

"Choice3 ", 

"Choice4 ", 

"Choices 
"Choices ", 

"Exit7 

„»}. 

byte *Box3[] = 

{"MENU3 
"Choicel ", 

"Choice2 ", 

"Choice3 
"Choice4 ", 

"Exit5 


byte *Box4{] - 
("MENU4 
"Choicel " 
"Choice2 
"Choice3 
"Choice4 " 
"Exit5 
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BOXREQ box_l = 

{ B0X_R£Q ,0,11, ’ 3 1 ,5,2, TRUE, 

TRUE, 5, FRM , ’5' , '5' , 5, NIL, 0,2}; 

BOXREQ box_2 = 

{ 80X_REQ , 1, 11, ' 3‘ , 26. 2, TRUE, 

FALSE, 7, FRM, '6', '5', 9, NIL, 0,2); 

BOXREQ box_3 = 

{ BQX_REQ, 2 , 1 1 , ' 3 ’ , 47, 2, TRUE, 

FALSE, 5, FRM, '6', '5', 7, NIL, 0,2}; 

BOXREQ box_4 = 

{ BOX_REQ,3, 11, '3' , 68, 2, TRUE, 

FALSE, 3, FRM, '6', ’ 5 ' , 7 , NIL, 0,2}; 


/* DISPLAY TITLE OF BOX ONLY */ 
byte *BoxTit1es[] = 

{"SESSION MENU2 MENU3 


BOXREQ box_Tit1es = 

{ BOX_REQ , 4 , 72 , 1 3 ' , 6, 2, FALSE, 

FALSE, 2, NOF, '6’, '5’, 2, NIL, 0,2}; 

/* ORGANIZE THE FILLING OF EACH BOX •/ 

PILLBOXES fillboxes[] * 

{ { &box_l, Boxl }, 

{ &box_2, Box2 }, 

{ &box_3, Box3 }, 

{. &bOx_4, Box4 }, 

{ &box_Titles, BoxTitles }, 

{ NIL, NIL } 

}; 




/* ORGANIZE THE ADDRESS OF EACH BOX »/ 

ALLBOX al"!_bax[] = 

{ { &box_l, handle_boxl }, 

{ ibox_2, hand1e_box2 }, 

{ &box_3, handle^box3 }, 

: { &box_4, hand1e_box4 }, 

{ &box_Tit1es, NIL } 

}; 


1: Example 1 


MENU4" , 
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/* NEEDED FOR THE INITIALIZATION OF THE MENU SYSTEM V 



FIELD errStr = {22,1, NIL}; 

DSPREQ errOsp = 

{ 

DSP_R£Q, 

0, 

ERROR_WIN, 

{byte *) SerrStr 
} ■ 

FIELD noTitle = {1,1,'"’ }; /* empty string */ 

WINOOWREQ error_win = 

{ WINOOW_REQ, 0-, ERROR_WIN, STATIC, 40,40, ’2', 1, 20, 

FALSE, 20, 20, NOF, FALSE, '7', SnoTitle, NIL }; 

y., 

/- USED TO DISPLAY WHICH CHOICE WAS MADE */ 



FIELD Title = {10,26, "String Window and Choice Number" }; 

byte P_ch[2] = {0x00, 0x00}; 

FIELD_OEF Choice_Conf = 

{TRUE, 12, 26, NIL, 12, 46, p_Ch }; 

FI£LQ_SEQ Ch_C = { 4Choice_Conf , NIL }; 

DSPREQ Choice_Str = 

{ DSP_REQ, 0, CHOICE_WIN, }; 

WINDOWREQ clloice_win =■ 

{ WINDOWJ1EQ,0,CHOICE_WIN, STATIC, 35,35, 1 2 ' , 26, 10, 

TRUE, 12, 15, FRM, FALSE, '7', iTitle, &Ch_C }; 

/* end uiTab.c -•/ 
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* File name: uiiab.h 

* Description: Definitions used for the user interface. 

* 

* Version Date ID Comment 

* 

« 1.0 Q3Q790 RHT Created. 

4 * • * * 4 * « * 4 * 4 « * * 4 •«« 4 * * 4 * * * 4 * * 4 4 4 4 4 4 4 * « 4 4 ************* 4 4 * « 4 * 4 4 « 4 *•*•»** / 

#def ine NUM_OF_WINOOWS 30 /* Number of windows */ 

^define NllM_OF_BOXES 30 /* Number of structures */ 

/• 

* System arrays. 

•/ 

extern DISPLAY dsp[]; 
extern- BOX box[]; 

^define ERRQR_WIN 0 

^define CHOICE_WIN 1 

/• 

* External declaration of box structures, (declared in uiTab.c) 

*/ 

typedef struct 

{ 

BOXREQ *box ; 

int (*func)(): /* Pointer to a specific function */ 

> ALLBOX; 

typedef struct 

{ 

BOXREQ *box ; 
byte * 1 ist ; 

} FILLBOXES; 
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/* 

* External declaration of boxes. 

*/ 


extern BOXREQ 
extern BOXREQ 
extern BOXREQ 
extern BOXREQ 
extern BOXREQ 


box_l ; 
box_2 ; 
box_3 ; 
box_4 ; 
box_Titles; 


extern hand1e_boxl( ); 
extern hand1e_box2{ ); 
extern handl e_box3( } ; 
extern tiand1e_box4( ) ; 

extern ALLBOX a11_box[]; 
extern fILLBOXES filTboxes[]; 


extern WINDOWREQ error_win; 
extern WINDOWREQ ctioice__win; 


extern DSPREQ Choice_Str; 
extern FIELD_QEF Choice_Conf •, 
extern FIELD_SEQ Ch_C; 


extern byte *BoxlQ; 
extern byte *Box2[]; 
extern byte *Box3[]; 
extern ' byte *Box4[]; 

' extern byte *BoxTit1es[]; 

/* end uiTab.h 


V 
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Introduction 


EXAMPLE TWO: 
PARAMETER INPUT 


This appendix contains the files for example 2. There are 
three required files. 

• ex2.c 

• uitab.c 

• uitab.h 

Note that the uitab.c and uitab.h files are not the same files as 
used for example 1. These files contain the text to be 
displayed in the box and window. 

This example consists of one box, the list selector shown in 
Figure 5.2-1,. and two windows. Only one of the windows will 
be displayed at any given time, depending on the selection 
made. ‘ 

If Load or Save are selected, a scrolling window is displayed 
containing information or which selection was made. 

If Setup is selected, the Layer 2 configuration window, Figure 
5.2-1, is displayed! This window utilizes an 1NPUT_REQ to 
allow the user to change the configuration parameters. This 
also illustrates overlaying windows. 


— & 


SESSION 

, > Load 
Save 
Setup 
Exits 


C- Shell 



Layer 2 configuration 


TEI 

. : 127 

N2Q1 

: 260 

SAPI 

: 63 

N200 

: 10 

T200 

: 10 

Window 

: 3 

T203 

: 20 

Modulus 

: 128 

Encode 

: NRZ 

TEIval 

: AUTO 



TEI value 0- 127 



Figure 5.2-1: Example 2 
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File name: 
Description 

Version 

1.0 


ex2.c 

Depending on the choice made within a list box, 
either display a. scrolling window or an input request 
allowing fields to be edited. 

Date ID Comment 


030790 RHT Created. 


/ 


^include "mainsym. h" 

^include "ui ,h" 

^include "uitab.h" 

main() 

{ . 

BOXCONF conf ; 

••••*»/ 

/* INITIALIZE MENU SYSTEM */ 

i nitUI (dsp .box ,&error_wi n , NUMjDF_WINDOWS , NUM_OF_BOXES ) ; 



/* MOVE STRING FIELDS INTO THEIR ASSOCIATED ARRAY */ 



f illBoxArea(&box_l .Box 1) ; 


/* DISPLAY EACH LIST BOX UNLESS ESC OR CANCEL IS SELECTED */ 

/c «****« **«*«**•**«***•****•*««**«•* *»**♦******************/ 

f°r(;;) { 

box_l. choice - TRUE; /* set re-display */ 

userInterface(&box_l ,&conf , dsp, box); /* display list box */ 

switchfconf .exit) { 

case GO: /»•*»••**»»•**»»»*••*•»«»/ 

case RIGHT:/* IGNORE THESE ENTRIES */ 
case LEFT: 

break; 

»♦*«*•*••*•? 

/* HANDLE THE CHOICE MADE AND SET »/ 

/* THE HIGHLIGHT TO THE SAME CHOICE */ 

****** 

case RTN: hand! e_choice( conf .choice); 

box_l. offset = conf. choice; /* highlight the */ 
box_l.setRow = conf. row; /* selec. position */ 

break; 
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case ESC: 

case CAN: /» RESET, CLEAR SCREEN THEN EXIT */ 
default: /***••*»«**•»•«*»**»»*****»•»*•*«*/ 

printf (RESET) ; 
printf (CLEAR) ; 
enabl ecur(_stdvt ) ; 
exit(C); 

' } 

’ > 

} 


handle_choice( choice) 
int choice; 

c 

byte ch; 

switch (choice ) { 

case 1: userlnterf ace(&dsp_win ,NIL, dsp-, box ) ; /* display window 

message. text = msgl; 

userlnterf ace(&message, NIL , dsp , box) ; /* display message */ 

break; 

case 2: userInterface(&dsp_win,NIL,dsp,box); /* display window *'/ 
message. text = msg2; 

userInterface(&message,NIL,dsp,box); /« display message */ 
break; 

case 3: userInterface(&dspwERA,NIL,dsp,box); /* erase dsp_win */ 
userInterface(&conf2_wi n , NIL, dsp ,box) ;/* display window */ 
irWork = ir; 

userInterface(&conf2_input, &ch); /* display contents */ 

if ( ch -= GO ) ir = irWork; /* save choices on GO */ 

conf2_win. event = ERASEW_REQ; 

userInterface(&conf2_win,NIL,dsp,box) ;/* erase window */ 

Conf2_win .event = WINDOW_REQ; 

break; 

case 4: printf (RESET) ; /• exit program */ 

printf (CLEAR) ; 
enablecur(_stdvt) ; 
exit(O); 

} 

> 
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* ** 





File name; 

uitab.c 



Description ; 

Initialize all 

user interface windows and boxes. 


Version 

Date ID 

Comment 






1.0 

030790 RHT 

Created . 


^include "mainsym.h" 

^include "ui.h” 

#include "uitab.h" 

DISPLAY dsp[NUM_QF_WINDOWS] ; /* System configuration. */ 

BOX bax[NUM_0F_B0X£S]; /* System configuration. •/ 

byte msgl[] = "The text for choice 1 - Load."; 
byte msa2[1 = "The text for choice 2 - Save."; 

/»«**«****» *********************** j 

/* DISPLAY ENTIRE BOX OF CHOICES «/ 

^ 444444444444444444444444444444444 / 

byte *Boxl[] = 

{"SESSION ", 

"Load 

"Save 

"Setup ", 

"Exit5 ", 

w n ^ . 

BOXREQ box_l = - 

{ B0X_R£Q, 0 , 0 , 11, 1 3 ’ , 5, 2, TRUE, 

TRUE, 6, FRM, '6’, '5’, 6, NIL, 0,2}; 

,.,,4...... 

/* NEEDED FOR THE INITIALIZATION OF THE MENU SYSTEM »/ 

. 4 . 444444 . 44 .,. 4 . 4444 ,., .,,. 44 ... . 44 . 444 / 

FIELD errStr = {22,1, NIL}; 

DSPREQ errOsp = 

{ 

OSP_REQ, 

0, 

ERR0R_WIN, 

(byte *) SerrStr 

}; 


FIELD noTitle = {20,1, NIL}; /* empty string •/ 
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WINDOWREQ error_win = 

{ WINDOW_REQ,0,ERROR_WIN, STATIC. 40,40, ' 2 ' , 1, 20, 
FALSE, 20, 20, NOF, FALSE, '7', SnoTitle, NIL }; 

.I.....,*,*.,*.,........... 

/* DISPLAY MESSAGE FOR SELECTION MADE */ 



FIELD Title = {6 , 45 , ”\033[36mScroll ing Window Title" >; 

i 

WINDOWREQ dsp_wi n = ■■ 

{ WINDOW_REQ, 0, DSP_WIN , SCROLLING, 36,35, '2', 40, 6, 
FALSE, 8, 10, FRM,‘ FALSE, ’7', STitle, NIL >; 

DSPREQ message - 

{ 

DSP_REQ, 

0, 

DSP_WIN , 

NIL}; 

ERABREQ dspwESA = 

{ 

ERASEW_REQ, I 

0, [ 

DSP_WIN} ; 

/ 

/» WINDOW USED FOR USER INPUT •! 



FIELD conf2Title = {8, 13, "Layer 2 configuration"}; 

WINDOWREQ conf2_wi n = 

{ WINDOW_R£Q , 0 , C0NF2_WIN , STATIC, 44,60, '3', 3, 8, 
TRUE, 4, 20, FRM, FALSE,, '5', &conf2Title, NIL }; 


/* ALLOW FOR SPACE-BAR TOGGLE OF FIELD WITH DEVEOLPER DEFINED RESULTS •/ 



SETUP_TYPE irWork, ir; /* initial and saved values */ 

FKEY_FI£LQ_TYP£ encode_f key[] = j 

{ {ON , "NRZ " , "0" , NIL} , {ON , "NRZI M , " 1” ,NIL} , {Oxf f j NIL} }; 

FKEY_FI£LD_TYPE mod_fkey[] = 

{ {ON, "8 “ , *0" .NIL} , {ON, "128", "1", NIL}, {Oxff NIL} }; 

FKEY_FIELD_TYP£ tei_fkey[] = 

{ {ON, "AUTO " , "0” ,NIL} , {ON, "FIXED" , "2" , NIL} , {Oxf f NIL} }; 
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* 

/* WHERE AND HOW TO DISPLAY THE USER I/O WINDOW */ 



I N PUT_F I E LD_TY PE conf 2_f iel ds[] = 

{ 


{10,16,3 , 8i rWork . tei , 

1,0,0, 10,5, “TEI 

: ” , "TEI_COM ”, 9 , 1,5 , 5 , 

1,0,127,0}, 

{ 12, IS, 2, &i rWork. sap i , 
1,0,63, 0}, 

1,0,0, 12,5, "SAPI 

: ” , "SAPI_C0M“ , 0, 2 , 6, 6 , 

{14, 16,4, ai rWork . t200, 
■0,0,0, 0}, 

1,0,0, 14,5, "T200 

: " , ”T2D0_C0M" , 1,3, 7,7 , 

{15,16,4 , &i rWork . t203 , ■ 

1,0,0, 16,5, "T203 

"T203_COM" , 2 ,14 1 8 , 8 . 

0,0,0, 0}, 



{18, 16 , 1 ,&i rWork. encode. 1 ,0 , 0 , 18,5, "Encode 
0,G,0,encode_fkey}, 

: " , ”ENC_COM ", 3, 5, 9, 9, 

{10,38,3,&irWork.n201, 

1,0.0. 10,28, "N201 

: " , "N20 1_C0M" , 4 , 6 , 0, 0 , 

1,1,512,0}, 

{12 ,38 ,4,ai rWork,n200, 

1,0,0, 12,28, "N200 

: " , "N200_COM" , 5 , 7 , 1, 1 , 


1,2,9999,0}, 

{14, 38, l.airWork. window, 1,0,0, 14,28 , "Window : ” , "WIN_COM ", 6,8, 2, 2, 
1,1,7, 0), 

{16,38, l.airWork. modulus, 1,0,0, 16,28j’'Modulus :",”MOD_COM ", 7,9, 3, 3, 
0,0,0,mod_fkey}, : 

{18, 38, l,ai rWork. tei_f lag, 1,0,0, 18,28, "TEI val : " , "TEIA_C0M" ,8 ; 0, 4, 4, 
Q,0,0,tei_fkey}, 

{ 0 , 0 , 0 , 0 , 0 , 0 , 0 , 0 , 0 , 0 , 0 , 0 } 

,J }: 

INPRE0 conf2_input ■ 

{ INPUT_REQ,0,conf2_fields,0, CYAN, YELLOW, GREEN, 20, 23, 

MAGENTA, 20, 5}; 

/* — enc j uiiab.c */ 
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/ 


File name: 
Description: 
Version 
1 . 0 


uiTab.h 

Definitions used for the user interface. 
Date ID Comment 

030790 RHT Created. 


/ 


#def ine 

NUM_OF_WINDOWS 

30 


/» 

Number of windows */ 

#def ine 

NUM_0F_B0X£S 

30 


/• 

Number of structures */ 

extern 

DISPLAY dsp[] ; 



/* 

System arrays. */ 

extern 

BOX box[]; 



/• 

System arrays. */ 

#def ine 

ERR0R_WIN 


0 



#def ine 

DSP_WIN 


1 



^define 

C0NF2_WIN 


2 



/• 







* External declaration of boxes. 

*/ 


extern 

BOXREQ 

box_l; 

extern 

byte 

*Boxi[]; 

extern 

WINDOWREQ 

error_win ; 

extern 

WINDOWREQ 

dsp_win; 

extern 

WINDOWREQ 

conf 2_win ; 

extern 

DSPREQ 

message; 

extern 

ERABREQ 

dspwERA ; 

extern 

INPREQ 

conf2_input; 

extern 

INPUT_FIELD_TYPE conf 2_f i el ds[] j 
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typedef struct 

{ 


int portnum; 

int tei ; 

int s ap i ; 

int mode; 

int D_chan; 

int Bl_chan; 

int B2_chan; 

int interface; 

int station; 

int encode; 

unsigned int bitrate; 

int tei_flag; 

int t200; 

int t2Q3; 

int n201; 

int n200; 

int window; 

int modulus; 

int config; 

int phys_setup; 

int bit_inv; 

int nt_power; 

> SETUP_TYP£ ; 


/* Structure for setup layer i and 2 */ 


extern SETUP_TYPE ir; 
extern SETUP_TYPE irWork; 


/* Text message output */ 
extern byte msgl[]; 
extern byte msg2[]; 


end 


uiTab.h 


»/ 
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EXAMPLE THREE: 

LISTING FILES FROM A DIRECTORY 


This appendix contains the fiies for example 3. There are 
three required fiies. 

• ex3.c 

• uitab.c 

• uitab.h 

Note that the uitab.c and uitab.h files are not the same fiies as 
used for examples 1 and 2. These files contain the text to be 
displayed in the box and windows. 

This example consists of two box, the two list selectors shown 
in Figure 5.3-1 and two windows. The boxes and windows 
displayed depend on the selection made. 

if Load is selected, the display will appear as shown in Figure 
5.3-1. The second box or list selector is displayed using 
getFileChoice to display the list of files. Once a file is 
selected, it is marked with an asterisk, the border of the box 
changes to include an arrow and a static window showing the 

• choice is displayed. 


-G 


SESSION 

> Load 
Save 
Exit5 ■ 


ASYNC.CO 
BSC.CO 
BSCTAB.CO 
CHAMPS. CO 
CONVERT.CO 
CPM.CO 
•DDCMP.CO 
FLH.CO 
FLHD.CO 
FRAMEM.CO 
FRMDMI.CO 
FRMENU.C.O 




String Selected - Choice Number 
DDCMP.CO 1 


C-Shell 


I 


Figure 5.3-1: Example 3 


If Save is selected, a scrolling window is displayed with the 
message The choice made was SAVE. 
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File name: ex3.c 

Description: Depending on the choice made from a list box, display 
either a scrolling window or another box. This other 
box displays a list of directory files. When a selection 
has been made it is marked and a static window displays 
the filename and choice number. 

Version Date ID Comment 


1.0 030790 RHT Created. 


#include "mainsym.h" 
^include "ui.h" 
#include "uitab.h" 

main( ) 

{ 

' BOXCONF conf ; 




/» INITIALIZE MENU SYSTEM •/ 



initUI(dsp,box,&error^win,NUM_QF_WINDOWS,NUM_OF_BOX£S); 



/* MOVE STRING FIELDS INTO THEIR ASSOCIATED ARRAY V 

/ /**<4»«*4*9«**««**4M**4J|4**44*****a*«*M«««*4*t$*< f 

f i HBoxArea(&box_l ,Box 1) ; 



/• DISPLAY EACH LIST BOX UNLESS ESC OR CANCEL IS SELECTED «/ 

for(;;) { 

box_l, choice = TRUE; /* set re-display */ 


userlnterf ace(&box_l ,&conf ,dsp,box) ; /* display list box •/ 

switch(conf .exit) { 

case GO: /•«••«••••••*•••••***••»•/ 

case RIGHT: /* IGNORE THESE ENTRIES */ 
case LEFT: /»«**•»»**•••*»•••»»*••«»/ 

break; 
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/»** 

/• HANDLE THE CHOICE MADE ANO SET •/ 

/* THE HIGHLIGHT TO THE SAME CHOICE */ 

/**** •*«.»./ 

case RTN: hand!e_choice(conf .choice) ; 

box_l. offset = conf!choice; /* highlight the */ 

box_l.setRow = conf.row; /* selec. position */ 

break; 


} 


} 


case ESC: /*••**»•«■»••*»•»*•»•«»••*•/ 

case CAN: /• RESET, CLEAR THEN EXIT V 
default : /***»•»«»»**«»•»*»»•■»•»»•/ 

end_program( ) ; 

> 


/* 

* Determine how .to handle the choice made. 

•/ 

h and le_choice( choice) 
int choice; 

{ 

switch (choice ) { 

case 1: /* load •/ 
handle_load() ; 
break; 

case 2: /* save */ 

userInterface(&excb£RA, NIL,dsp,box ) ; 
userlnterf ace (SchoicewERA, NIL,dsp,box); 
userlnterf ace(&dsp_w in ,NIL,dsp,box) ; 
userlnterf ace (&message, NIL, dsp , box) ; 
break; 

case 3: /* exit program */ 
end_program( ) ; 

} 

} 


/* erase excF_box */ 

/* erase choice_win */ 
/* display window */ 

/* display message */ 
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/* 

* Display a box containing a list of the files within \tekel ecXsystem 

* which end with the extension 'co' . 

V 

handle_load( ) 

{ 

byte *pfile; 

BOXCONF conf ; 

userInterface(&dspwERA,NIL,dsp,box) ; /* erase dsp_win */ 

user!nterface(&choicewERA,NIL,dsp,box) ; /* erase choice_win */ 

pfile = getFileChoice(&excF_box,EXC_PATH,'’co" , 
excF title, excErr, FALSE ,NIL,0 ,&conf ) ; 
if(conf.exit == CAN || conf. exit == ESC) return; 
cSToggl e{ excF_box . p , conf . choice.O , ' * ’ , ' ' ) ; 
excF_box. choice = FALSE; 
ex cf_box .frame = FRM+RAR; 
excF_box . setRow = conf. row; 
excF_box.of fset = conf. choice; 
userInterface(&excF_box ,&conf , dsp, box) ; 
excF_box. choice - TRUE; 
excF_box . frame = FRM; 
excF_box . setRow = excF_box . row; 
excF_box. offset = 0; 
handle_box( conf .choice , pfile) ; 

} • 

/* 

® Display a window containing the string and choice number selected. 

V 

hand! e_box( choi ce.pstr) 
int choice; 
byte *pstr; 

{ 

/*»*•••••»«**•*•••••**»«•*•*•»****•**/ 

/* SET THE STRING AND CHOICE NUMBER */ 

Choice_Conf .title = pstr; 

i toa( choi ce, Choi ce_Conf .output) ; 

/• DRAW THE OUTLINE */ 

choice_win. event = WINDOW_REQ; 

userlnterf ace(8.choice_win .NIL, dsp ,box) ; 

/•****«** 4 **«««*********«**«*«**«*«*/ 

/* INSERT THE TEXT INTO THE WINDOW •/ 

/**«** 44 * 9 ** 4 « 4 *****»** 4 * 4 «**•»*****/ 

choice_win .event = DSP_R£Q; 

Ch_C.f[0]->changed = TRUE; 

userlnterf ace (Schoi ce_win ,NIL, dsp, box ) i 

} 


/* mark choice •/ 

/* highl ight off */ 
/* add arrow */ 

/* keep the list */ 
/* displayed */ 

/* display box */ 

/* highlight on */ 

/* remove arrow V 
/* reset the list */ 
/* displayed */ 

/* display choice V 
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/• 

* Convert the integer to an ascii String. 

•/ 

itoa(n, s) 
int n; 
byte s [ 4] ; 

{ 

int i=0, j, trap; 

do { /* convert integers to ascii in reverse order »/ 

s[i++] = n % 10 + ’O’ ; 

} while( (n /= 10) > 0); 

s[i] = ’ \0 ' ; 

for(i=Q, i=strlen(s)-l; i<j; i++, j — ) { /* fix the order of digits */ 

tmp = s[i]; 
s[i] = s[j]; 

S[j] = tmp; 

} 

> 


• Reset attributes, turn cursor on and then exit to the C-sheil. 

•/ 

end_program( ) 

{ 

printf (RESET) ; 
printf (CLEAR) ; 
enabl ecur(_stdvt) ; 
exit(0) ; 
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Fite name: uitab.c 

Description: Initialize all user interface windows and boxes. 


* 

Version 

Date 

ID 

Comment 


e 

«*** 

1.0 

030790 

RHT 

Created. 



^include "mainsym.il" 

^include "ui.Ji" 

^include "uitab.h 11 

DISPLAY dsp{NUM_OF_WINDOWS]; /• System configuration. •/. 
SOX box[NUM_0F_8QXES] : /* System configuration. V 

/* OISPLAY ENTIRE BOX OF CHOICES •/ 

/**&«**«>**** •••»******««** *»***•**/ 

byte *Boxl[] = 

{"SESSION ", 

"Load 
"Save 
_ "ExitS 

BOXREQ box_l = 

{ B0X_R£Q , 0 , SESSI0N_B0X , 1 1 , ' 3 ’ , 5, 2, TRUE, 

TRUE, 5, FRM, '6', ’5', 5, NIL, 0,2}; 


/* DISPLAY CHOICES OF FILE NAMES •/ 

BOXREQ excF_box = 

{ BOX_R£Q, 0, FILEJ30X , 17, '2', 5, 8, TRUE, 

TRUE, 19, FRM, '4', '5', 100, NIL, 1,9}; 

byte excFtitle[16] = "DIRECTORY FILES"; 

byte exc£rr[41] = "NO ’*.co’ FILES, PRESS CANCEL TO CONTINUE"; 
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/«**•*•• 

/• HEEDED FOR THE INITIALIZATION OF THE MENU SYSTEM */ 



FIELD errStr = {22,1, NIL}; 

DSPREQ errDsp = 

{ 

DSP__REQ , 

0 , 

ERROR_WIN, 

(byte *) SerrStr 

}: 


FIELD noTitle = {20,1, NIL}; 1 * empty string */ 

WINDOWREQ errorjuin = 

{ WINDOW_REQ,Q,£RROR_WIN, STATIC, 40,40, ' 2 1 , 1,. 20, 
FALSE, 20,- 20, NOF , FALSE, '7' , &noTitle, NIL }; 




/• DISPLAY A MESSAGE FOR THE. SAVE SELECTION V 



FIELO Title = {6, 45, "\Q33[36mScrolling Window Title" }; 
WINDOWREQ dsp_win = 

{ WINOOW_REQ, 0, DSP_WIN, SCROLLING, 35, 35 , ' 2 ’ , 40, 5^ 
FALSE., 8, 10, FRM, FALSE, '7-, STitle, NIL }; ' 




/* USED TO DISPLAY WHICH CHOICE WAS MADE I V 

........... ...«... v 

FIELD Title2 = {10 ,30 , "String Selected - Choice Number" }; 

byte p_ch[4] = {0x00, 0x00, 0x00, 0x00}; 

FIELD_DEF Choice_Conf = 

{TRUE, 12, 32, NIL, 12, 52, p_ch }; 

FIELD_SEQ Ch_C = { &Choice_Conf , NIL }; 

DSPREQ Choice_Str = 

{ ' DSP_REQ, 0, CHOICE_WIN , NIL }; 

WINDOWREQ choice_win' = 

{ WINOOW_REQ,0,CHOICE_WIN, STATIC, 35,35, '2', 30, 10, 
TRUE, 12, 15, FRM, FALSE, V, &Title2, &Ch_C }; 
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/* RE-OISPLAY AND ERASE WINDOWS */ 



DSPREQ message = 

{ 

0SP_REQ, 

0 , 

' DSP_WIN, 

"The choice made was SAVE”}; 

ERABREQ dspwERA = 

{ 

ERASEW_REQ, 

0 , 

OSP.WIN}; 

ERABREQ excbERA = 

{ 

ERASEB_REQ, 

0 , 

FILE_BOX}j 

ERABREQ choicewERA = 

{ 

ERASEW_R£Q, 

0 , 

CNGICEJfIN}; 


/* end uiTab.c ’ */ 
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Fils name: uiTab.h 

Description: User interface definitions. 

Version Date ID Comment 


* 

1.0 

030790 

RH 

#def i ne 

NUM OF WINDOWS 30 

/» 

#def ine 

NUM_QF_B0XES 30 

/• 

#def ine 

EXCJ’ATH 

"WtekelecX 

^define 

£RRQR_WIN 

0 

#def ine 

DSP_WIN 


1 

#def ine 

CHOICE_WIN 

2 

#def ine 

SESSION J 

BOX 

0 

#def ine 

FIIE_B0X 


1 

extern 

BQXREQ 

box_l; 


extern 

B0XREQ 

excF_box ; 


extern 

byte 

*6oxl[3; 


extern 

WINOOWREQ 

errarjain; 

extern 

WINOOWREQ 

dspjain ; 


extern 

WINDOWREQ 

choice_«in; 

extern 

DSPREQ 

message ; 


extern QSPREQ 

Choice_Str; 

extern 

FIELD_DEF 

Choice_Conf ; 

extern 

FIELD_S£Q 

Ch_C ; 


extern 

ERA8REQ 

dspwERA; 


extern 

ERABREQ 

excbERA ; 


extern 

ERABREQ 

choicewERA; 

extern 

byte 

*getF i 1 eChoi ( 

extern 

byte 

excftit1e[]; 

extern 

byte 

excErr[] ; 


end uiTab.h 
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INCLUDE FILE UI.H 


Introduction 


T EXELEC 


This appendix contains the file ui.h. This file must be included 
in all applications using the user interface as describe in this 
document. This file contains the structure definitions and 
global variable definitions. 


/ 


* Rile name: ui.h 


Description: This file contains the definition of the 

structures and contants used when interacting 
with the windowing user interface. 

Functions: 


Version 

Date 

10 

Comment 

O-.L 

' 121288 

TEKELEC/IA 

•First created 

1,0 

021188 

TEKELEC/IA 

Switch Release 1.0 

1.1 

021489 

TEKELEC/IA 

Ntsim development 

1.2 

022189 

TEKELEC/EvdM 

Input 

1.3 

022289 

TEKELEC/EvdM 

Input Field Struct 

1.4 

022289 

TEKELEC/IA 

choice in B0X_REQ 

1.5 

030189 

TEKELEC/IA 

EDIT_REQ 4 EDITREQ. 

1.6 

030289 

TEKELEC/IA 

ERASE_FIELD 4 BINARY_INPUT 

1.7 

030689 

TEKELEC/IA 

SCROLL_INPUT 

1.3 

030789 

TEKELEC/IA 

scrollBuf in EDITREQ 

1.9 

030889 

TEKELEC/IA 

SCROLL_REQ 4 SCROLLREQ 

1.10 

032989 

TEKELEC/IA 

offset parameter in list box 

1.11 

032989 

TEKELEC/IA 

row in BOXCONF 

2.0 

041389 

TEKELEC/IA 

NT/TE SIMULATOR 

2.1 

112089 

TEKELEC/IA 

B0XREQ edit sim 3.0 


/ 


A-1 


7 / 30/90 



Application Programming Interface 


App A: ui.h 


/* 

• Window types. 

*/ 

^define STATIC 0 

#def ine SCROLLING 1 


/* 

* Frame Flags. 

*/ 


#def ine 

NOF 

0x0000 

#def ine 

LEFTF 

0x0001 

#def ine 

TOPF 

0x0002 

#def ine 

RIGHTF 

0x0004 

#def ine 

80TF 

0x0008 

#def ine 

FRM 

LEFTF+TOPF+RIGHTF+BOTF 

/» 

* Arrow Flags. 


*/ 



#def ine 

LAR 

0x0100 

#def ine 

TAR 

0x0200 

^define 

RAR 

0x0400 

#def ine 

BAR 

0x0800 

#def ine 

ARS 

LAR+TAR+RAR.+6AR 

/* 

* . Edit modes. 

i 

*/ 



#def ine 

0W_M00E 

0 

#def ine 

INS_M0DE 

1 

typedef 

struct 


{ 

byte 

•area; 


byte 

•next; 


byte 

•previous; 



}LINE ; . 

typedef struct 

{ 

LINE ’free; 
LINE "used; 
LINE “last; 
} SCRAREA; 
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/* 

• Window administration structure. 
V 


typedef struct 
{ 

byte 

pos[8] ; 

byte 

color[6] ; 

byte 

text[500] ; 

int 

col ; 

int 

row; 

int 

mi nRow ; 

int 

maxRow; 

int 

Ten; 

int 

strLen ; 

int 

frame; 

byte 

bcolor;- 

int 

init; 

SCRAREA 

*p; 

int 

type; 

int 

back; 

int 

oldRow; 

}DISPLAY ; 


/• 

* Box administration structure. 

*/ 


typedef struct 
{ 


byte 

pos[8] ; 

byte 

Color[6] ; 

byte 

text[500] ; 

int 

col ; 

int 

row; 

int 

mi nRow; 

int 

maxRow; 

int 

Ten; 

int 

strLen ; 

int 

f rame ; 

byte 

bcolor; 

int 

init; 

SCRAREA 

*p; 

byte 

rev[5] ; 

byte 

dummy,; 

int 

lines ; 

int 

offset; 

int 

setRow ; 


/* int edit; V 

}BOX ; 


/•l. 10*/ 
/•1.12V 
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/* 


•/ 


System arrays. 


extern DISPLAY dsp[] ; 
extern BOX box[]; 


/• 

* 

• STATIC WINDOW DEFINITIONS. 


*/ 


^define MAX^FIELDS 30 

typedef struct 
{ 


int 

changed; 

int 

rowT ; 

int 

col T ; 

byte 

’title'; 

int 

rowO; 

int 

colO; 

byte 

•output; 

} FIELD_0£F ; 


typedef struct 

{ 

FIELD_DEF *f [MAX_FIELDS] ; 
} FIELD_SEQ; 


/* 

* Event definitions. 

•/ 


#def ine 

WINDOW_REQ 

10 

#def ine 

DSP_R£Q 

11 

#def ine 

REiTrEQ 

12 

#def ine 

LED_REQ 

13 

#def ine 

B0X_REQ 

14 

#def ine 

BOX_CDNF 

15 

#def ine 

ERASEB_R£Q 

16 

#define 

ERASEW_REQ 

17 

#def ine 

INPUT_R£Q 

18 

^define 

EDIT_REQ , 

19 

#def ine 

STR_EDIT 

20 

Adef ine 

ERASE_FIELD 

21 

#def ine 

BINARY_INPUT 

22 

#def ine 

SCROLL_INPUT 

23 

#def ine 

SCROLL_REQ 

24 

^define 

BOX INPUT 

25 


/* user interface signals */ 


/•I . 7*/ 
/*1 . 9 */ 
/*! . 9 */ 
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/* 

* Event structure definitions. 

*/ 


typedef struct 

{ 

int event; 
int taskld; 
int window; 
byte ’text; 
}D$PR£Q; 


typedef struct 

{ 

int event; 
int taskld; 
int window; 
byte ’scrollBuf; 
byte ’max; 

}EDITREQ; /®1 . 8*/ 


typedef struct 

{ 

int event; 
int taskld; 
int window; 
byte ’scrollSuf; 
byte ’max; 
}SCROLLREQ; 


typedef struct 

{ 

int event; 
int taskld; 
int window; 
JERASEFIELD; 


typedef struct 

{ 

int event; 
int taskld; 
int window; 
JRELREQ; 


typedef struct 

{ 

int event; 
int taskld; 
int box; 
}ERA8REQ; 
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typedef struct 

( 

int row; 
int col; 
byte *str; 
} FIELD; 


typedef struct 
{ 


int 

event ; 

int 

taskld; 

int 

window ; 

int 

type; 

int 

len ; 

int 

strLen ; 

byte 

color; 

int 

col ; 

int 

row; 

int 

clear; 

int 

minRow; 

int 

maxRow; 

int 

.frame; 

int 

back; 

byte 

bcolor; 

FIELD 

♦title; 

FIELD 

•output 


}WINDOWR£Q; 


typedef struct 
{ 


int 

event; 

int 

taskld; 

int 

box ; 

int 

len ; 

byte 

color; 

int 

col ; 

int 

row; 

int 

clear; 

int 

choice; 

int 

maxRow; 

int 

frame ; 

byte 

bcolor; 

byte 

rev ; 

int 

lines; 

SCRAREA 

*p; 

int 

offset; 

int 

setRow; 


/* int edit; */ 

}BOXREQ; 
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typedef struct 

{ 

int event; 

int taskld; 

long int vtnum; ' 
byte *pleds; 

long int ledword; 
}LEDREQ; 


typedef struct 

{ 

int event; 

int exit; 

int choice; 

byte *str; 

int row; /’2.11 s / 

}B0XC0NF: 


typedef struct 

{ 

byte fkey; 

byte ’disp_text; 
byte ’value; 

byte ’link; 

} FKEY_FIELD_TYP£; 


typedef struct 
{ 


byte 

row; 

/* 

x position for field input 

»/ 

byte 

col umn; 

/• 

y position for field input 

»/ 

byte 

len; 

/* 

Max len of field 

•/ 

byte 

•buff; 

/» 

Input buffer 


byte 

• type; 

/* 

If 1, input = byte or int 

*/ 



/* 

If 0, input - string 

*/ 

byte 

lf_flag; 

/* 

If 1, insert If before null 

’/ 



/* 

for string input 

*/ 

byte 

arrow_f 1 ag ; 

/• 

If 1, display arrow 

*/ 

byte 

c_row; 

/• 

x position for field label 

•/ 

byte 

c_col umn ; 

/* 

y position for field label 

’/ 

byte 

*c_text; 

/* 

Field label 

*/ 

byte 

*c_buff ; 

/•■ 

Field comment 

*/ 

byte 

up-; 

/* 

Field no to go to for UP 

*/ 

byte 

down; 

7 * 

for DOWN 

»/ 

byte 

right; 

/* 

for RIGHT 

•/ 

byte 

left; 

/* 

for LEFT 

*/ 

byte 

num_chk; 

/• 

If 1, check range of input 

»/ 

unsigned int min; 

/’ 

Min value of input 

*/ 

unsigned int max; 

/’ 

Max value of input 

»/ 

FKEY. 

_FIELD_TYPE ’fkjnr; 

/* 

If riot 0, ptr to key field 

»/ 


} INPUT_FIELO_TYPE; 
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typedef struct 

{ 

int event; 

int taskld; 

INPUT_FIELD_TYPE »fp; 


byte 

ft; 

/* 

Index 

of 

start field 

V 

char 

*i_color; 

/* 

Color 

of 

field content 

*/ 

char 

*t_color; 

/» 

Color 

of 

field’ label 

*/ 

char 

*c_color; 

/* 

Color 

of 

coitimnet 

*'/ 

byte 

c_row; 






byte 

C_Co1 ; 






char 

*s_color; 

/* 

Color 

of 

status info 

V 


byte s_row; 

byte s_col ; 

JINPREQ; 

extern DSPREQ errOsp; 

I 

extern FIELD errStr; 


/* end u i.h */ 
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Appendix B: 

INCLUDE FILE MA1NSYM.H 


This appendix contains the fiie mainsym.h. It must be included 
in all applications using the user interface as described in this 
document. It includes the following information: 

• General symbols 

• Keyboard codes 

• Color commands 

• Screen attributes and commands 

• Port Definitions 

• Definitions for Ul frame and FSearch 

• Record structure 


File name: mainSym.h 

Description: This file contains the global symbols. 

Version Date ID Comment 


• 1.0 030790 RHT Created. 

********* ************************ ****************** ********************/ 

#include <fcntl .h> 

#include <mtosux.h> 

^include <stdio.h>- 
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/» 

» GENERAL USEFUL SYMBOLS 

»/ 


/•define byte • unsigned char 

extern byte orgC; 

extern byte termC; 

extern byte ‘interface, ‘device; 1 

extern int stand_type; 

extern byte *matlocRe{); 

extern byte *findChar(); 

extern tong int get_dest(); 

extern int rxlen; 

extern tong _stdvt, getch( ) ; 

extern char ‘mallocO! 

extern byte *f ind£leinent( ) ; 

extern int Semafore; 


/•define 

STOP 

0 

/•define 

CONT 

1 

/•define 

NIL 

OL 

/•define 

TRUE 

-1 ■ 

/•define 

FALSE 

0 

(/define 

YES 

0 

#def ine 

NO 

1 

^define 

OFF 

1 

#define 

ON 

0 

/•define 

MOO(x.y) 

( x X y ) 

i/define 

AND 

&& 

/•define 

OR 

11 

#def ine 

NONE 

-1 

/•define 

MAX_NUM 

51 

//define 

ELE_BUF_LEN 

257 

/•define 

MSG_BUF_L£N 

256 

/•define 

MAX_MSG_LEN 

MSG_BUF_LEN 

/•define 

NUM_OF_MESSAGES 

21 

/•define 

NUM_OF_CCITT 

30 
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» KEYBOARD 'CODE DEFINITIONS 

•/ 


#define 

FI 0x81 

#def ine 

F2 0x82 

#def i ne 

F3 0x83 

#def i ne 

F4 0x84 

#def ine 

F5 0x85 

#define 

F6 0x86 

#def ine 

F7 0x87 

#def ine 

F8 0x88 

#def ine 

F9 0x89 

#def ine 

F 10 0x8a 

#def ine 

keyO 

0x30 

#def ine 

keyl 

0x31 

#def ine 

key2 

0x32 

#def ine 

key3 

0x33 

^define 

key4 

0x34 

#def ine ' 

key5 

0x35 ■ 

#def ine 

keyS 

0x36 

#define 

key? 

0x37 

#def ine 

key8 

0x38 

#def ine 

key9 

0x39 • 

#def ine' 

UP 

0x0b 

#def ine 

DOWN 

0x0a 

#def ine 

RIGHT 

0x0c 

#def ine 

LEFT . 

0x08 

rfdef ine 

RTN 

OxOd 

#def ine 

DELETE 

0x7f 

#def ine 

ESC 

Oxlb 

#def ine 

CAN 

0x18 

#def ine 

GO 

0x19 

#def ine 

CTRL_A 

0x01 

#def ine 

CTRL_B 

. 0x02 

#def ine 

CTRL_C 

0x03 

#def ine 

CTRL_D 

0x04 

#def ine 

CTRL_E 

0x05 

#def ine 

CTRL_I 

0x09 

#def ine 

CTRL~N 

OxOe 

#def ine 

CTRL_P 

0x10 

#def ine 

CTRL_Q 

Oxll 


/• 

* SCREEN COMMAND MACRO 

*/ 


^define setScr{x) printf { x) ; ff I ush( stdout ) ; 


I 
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/* 

•» COLOR COMMANOS 

•/ 


#def i ne 

BLACK 

”\C33[3Qm" 

#def ine 

RED 

"\033[31m" ■ 

#def ine 

GREEN 

“\033[32ni" . 

#def ine 

YELLOW 

"\033[33m'' 

#def ine 

BLUE 

"\033[34m” 

#def ine 

MAGENTA 

"\033[35m” 

#def ine 

CYAN 

"\033[36m" 

#def ine 

WHITE 

"XOaSfSTm" 

#def ine 

BBLACK 

. “\033[40ni" 

#def ine 

BRED 

"\033[41m" 

#def ine 

BGREEN 

"XOSSCABm" 

#def ine 

BYELLOW 

“\033[43ni" 

#def ine 

BBLUE 

"\033[44m" 

#def ine 

BMAGENTA 

”\033[45m” 

#def ine 

BCYAN 

”\033[46in” 

Mdef ine 

BWHITE 

"MmOIsT 


/* 

* SCREEN 

ATTRIBUTES 


*/ 

#def ine 

RESET 

'■\033[0m" 

#def ine 

HIGHLIGHT 

*\033[lm"' 

#def ine 

UNDERLINE 

"\033[4nT 

#def ine 

BLINK 

"\033[5m'* 

#def ine 

REVERSE 

. "\033[7m" 


* SCREEN 

•/ 

COMMANOS 


#def ine 

POS_CUR 

"Sc[Sd;Xdf ” ,Oxlb 

#def ine 

OEL_EOL 

nc[OK" ,Qxlb 

#def ine 

DEL_EOS 

”Xc£OJ" , Oxlb 

#def ine 

CLEAR ‘ 

"Xc[2J",0xlb . 


/» 

* PORT DEFINITIONS 

•/ 

#def ine PORTA 0 

^define PORTB 1 
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■ Application Programming Interface 


App B: _ mai nsvm .h 


/* 

* DEFINITION FOR UI FRAME 

*/ 


#def ine 

UI 

0x03 

#define 

MEI 

0x0f: 

#def ine 

IDREQ 

0x01' 

#def ine 

IDASS ' 

0x02 

#def ine 

IDDENY 

0x03 

#def ine 

IDCRK 

0x04 

#def ine 

IDCHKACX 

0x05 

#def ine 

IDREL 

0x06 

*def ine 

IDCONF 

0x07 


/* 

• DEFINITION FOR FSearch 

•/ 


/* Directory record data lengths */ 


^define FN_LEN 8 

^define EX_LEN 3 

#define AT_LEN 1 

^define RS LEN 10 


/• filename length »/ 

/* extension length */ 

/* file attributes length */ 
/* reserved bytes length */ 


/* Directory Record Structure */ 
struct DREC 
{ 


char 


dc_fn[FN_LEN]; 


/* file name */ 

char 


dc_ex[EX_L£N]; 


/* file extension */ 

char 


dc_at; 


/* file attributes */ 

char 


dc_rs[RS_LEN]; 


/* reserved bytes */ 

unsigned 

short 

dC_tim; . 

/* 

time file was created */ 

unsigned 

short 

dc_dat; 

/• 

date of file creation */ 

unsigned 

short 

dc_str; 

/• 

starting cluster number */ 

unsigned 

long 

dc_fsz; 

/• 

file size (bytes) V 


}; 

extern exit_pgm(); 


. ; At 1 
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